25 |
26 |
--------------------------------------------------------------------------------
/img/cyclejs_logo.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
22 |
--------------------------------------------------------------------------------
/_includes/img/modules-foo-bar.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/_posts/2015-01-21-community.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Community"
3 | tags: chapters
4 | ---
5 |
6 | To engage with the community around Cycle.js, follow these resources:
7 |
8 | * The GitHub organization, [cyclejs](https://github.com/cyclejs), is the default location for finding most of the packages you'll need.
9 | * Ask, "_How do I...?_" questions in Gitter: [](https://gitter.im/cyclejs/cyclejs)
10 | * Report bugs, discuss, and propose significant changes as a [GitHub issue](https://github.com/cyclejs/cyclejs/issues).
11 |
12 | ### Resources
13 |
14 | Visit [Awesome Cycle.js](https://github.com/cyclejs-community/awesome-cyclejs) to see a curated list of examples, presentations, blog posts, utilities and resources built by the community.
15 |
16 | ### Acknowledgements
17 |
18 | - This project is a grateful recipient of the [Futurice Open Source sponsorship program](http://futurice.com/blog/sponsoring-free-time-open-source-activities).
19 | - [@TylorS](https://github.com/TylorS) and [@Frikki](https://github.com/Frikki/) for fantastic contributions and involvement with Cycle.js.
20 | - [@dobrite](https://github.com/dobrite) for [boilerplate reduction ideas](https://github.com/cyclejs/core/issues/56).
21 | - [Nick Johnstone](https://github.com/Widdershin/) for writing libraries and spreading the word about Cycle.js.
22 | - [@erykpiast](https://github.com/erykpiast) for pull requests and great ideas.
23 | - [@pH200](https://github.com/pH200) for pull requests and amazing contributions.
24 | - [@cgeorg](https://github.com/cgeorg), [@laszlokorte](https://github.com/laszlokorte), and others in the Gitter chat for ideas, feedback, and active involvement with Cycle.js.
25 | - Organizers and sponsors of [CycleConf](http://cycleconf.com/) for bringing the community together in one place.
26 |
--------------------------------------------------------------------------------
/_layouts/default.html:
--------------------------------------------------------------------------------
1 | ---
2 | layout: blank
3 | ---
4 |
5 |
20 |
21 |
22 |
{{ page.title }}
23 | {% if page.path %}
24 | Edit on GitHub
25 | {% endif %}
26 |
27 |
28 | {{ content }}
29 |
30 |
31 |
32 | {% if page.next %}{% endif %}
33 | {% if page.previous %}{% endif %}
34 |
35 |
36 |
37 |
38 | {% if page.next %}{% endif %}
39 | {% if page.previous %}{% endif %}
40 |
9 | {% include img/simple-human-computer.svg %}
10 |
11 |
12 | The computer usually "speaks" visual information through a screen, which the human can "listen". Through different devices, the computer can reach different human senses. The human, on the other hand, often "speaks" commands to the computer through its hand, manipulating a mouse or touching a screen.
13 |
14 | #### Human-Computer Interaction is a dialogue: an ongoing exchange of messages between both sides.
15 |
16 | Both parties are able to "listen" to each other, and utter messages through their devices. In other words, we can say the human and the computer are mutually observed, or simply having a dialogue. The reason why we point out "mutual observation" is because it is related to Reactive Programming and will affect how we model this system.
17 |
18 |
19 |
Similarity with Haskell 1.0?
20 |
21 | This same dialogue concept can be found in Haskell 1.0 Stream-based I/O, where type Dialogue = [Response] -> [Request] is the model of interaction with the Operating System. [Response] is a stream of messages from the OS, and [Request] is a stream of messages to the OS.
22 |
23 |
24 | Cycle.js' abstraction was discovered independently from Haskell's Stream I/O. We try to take some inspiration from Haskell's Dialogue whenever convenient, but there are a few conceptual differences. Not all problems with Haskell's Dialogue exist in Cycle.js or matter to Cycle.js users, and vice-versa. This is due to different execution environment assumptions and different design decisions on modelling event streams. If you want more details on this topic, the following GOTO talk is recommended, centered around the history and theory behind Cycle.js:
25 |
26 |
27 |
28 |
29 |
30 |
31 | The computer is made of devices to interact with the human. *Output* devices present information to the human, and *input* devices detect actions from the human. The human possesses *actuators* and *senses*, which are connected to the computer's *input* and *output* devices, respectively.
32 |
33 |
34 | {% include /img/actuators-senses-input-output.svg %}
35 |
36 |
37 | The *inputs* and *outputs* of the computer suggest the computer's role in HCI can be expressed as a function.
38 |
39 | {% highlight js %}
40 | function computer(inputDevices) {
41 | // define the behavior of `outputDevices` somehow
42 | return outputDevices;
43 | }
44 | {% endhighlight %}
45 |
46 | We do not yet know what `inputDevices` and `outputDevices` should be in JavaScript, but for now try to appreciate the elegance of `computer()` as a pure function. Refactoring and architecture is just a matter of choosing the right composition of functions to make up `computer()`.
47 |
48 | When talking about inputs, outputs, senses, and actuators, it becomes difficult to describe the difference between senses and inputs, other than the former is often associated with humans, and the latter with computers. From the computer's perspective, a microphone and its drivers are how the computer is able to *sense* auditory information. In essence, when we ignore the nature of the human body and the physics of computing machines, the human and the computer are both simply agents with senses and actuators.
49 |
50 | {% highlight js %}
51 | function computer(senses) {
52 | // define the behavior of `actuators` somehow
53 | return actuators;
54 | }
55 | {% endhighlight %}
56 |
57 | The agents in this interaction are now **symmetric**: the actuator of one is connected to the senses of the other, and conversely.
58 |
59 |
60 | {% include /img/actuators-senses.svg %}
61 |
62 |
63 | The diagram above is an [anthropomorphism](https://en.wikipedia.org/wiki/Anthropomorphism) of the computer. If we take the opposite approach of objectifying humans as machines, then both human and computer would be functions with inputs and outputs.
64 |
65 |
66 | {% include /img/hci-inputs-outputs.svg %}
67 |
68 |
69 | Which suggests the human would be a function from its senses to its actuators.
70 |
71 | {% highlight js %}
72 | function human(senses) {
73 | // define the behavior of `actuators` somehow
74 | return actuators;
75 | }
76 | {% endhighlight %}
77 |
78 |
79 |
JSConf Budapest talk
80 |
81 | Watch Andre Staltz's talk on What if the user was a function? which addresses the same topics as this chapter does.
82 |
83 |
84 |
85 |
86 |
87 |
88 | While these abstractions seem to be natural choices for user interfaces, many questions still remain:
89 |
90 | - What are the types of `senses` and `actuators`?
91 | - When is the `human()` function called?
92 | - When is the `computer()` function called?
93 | - If the output of one is the input of the other, how do we solve the circular dependency `y = human(x)` and `x = computer(y)`?
94 |
95 | These are questions that drive the core architecture of Cycle.js, but to understand our solution, we first need to understand reactive streams: our building block for everything in Cycle.js. [Keep reading](/streams.html).
96 |
--------------------------------------------------------------------------------
/_includes/img/main-domdriver-side-effects.svg:
--------------------------------------------------------------------------------
1 |
75 |
--------------------------------------------------------------------------------
/_includes/img/hci-inputs-outputs.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/_includes/img/actuators-senses-input-output.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/_includes/img/actuators-senses.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/_includes/img/custom-element-drivers.svg:
--------------------------------------------------------------------------------
1 |
74 |
--------------------------------------------------------------------------------
/_includes/homepage-content.md:
--------------------------------------------------------------------------------
1 |
Your app and the external world as a circuit
2 |
3 |
4 | {% include /img/cycle-nested-frontpage.svg %}
5 |
6 |
7 | Cycle's core abstraction is your application as a pure function `main()` where inputs are read effects (*sources*) from the external world and outputs (*sinks*) are write effects to affect the external world. These I/O effects in the external world are managed by *drivers*: plugins that handle DOM effects, HTTP effects, etc.
8 |
9 | The internals of `main()` are built using Reactive Programming primitives, which maximizes separation of concerns and provides a fully declarative way of organizing your code. The *dataflow* is plainly visible in the code, making it readable and traceable.
10 |
11 | ## Example
12 |
13 | {% highlight text %}
14 | npm install xstream @cycle/xstream-run @cycle/dom
15 | {% endhighlight %}
16 |
17 | {% highlight js %}
18 | import {run} from '@cycle/xstream-run';
19 | import {div, label, input, hr, h1, makeDOMDriver} from '@cycle/dom';
20 |
21 | function main(sources) {
22 | const sinks = {
23 | DOM: sources.DOM.select('.field').events('input')
24 | .map(ev => ev.target.value)
25 | .startWith('')
26 | .map(name =>
27 | div([
28 | label('Name:'),
29 | input('.field', {attrs: {type: 'text'}}),
30 | hr(),
31 | h1('Hello ' + name),
32 | ])
33 | )
34 | };
35 | return sinks;
36 | }
37 |
38 | run(main, { DOM: makeDOMDriver('#app-container') });
39 | {% endhighlight %}
40 |
41 |
42 |
43 |
44 | ## Functional and Reactive
45 |
46 | Functional enables "predictable" code, and Reactive enables "separated" code. Cycle.js apps are made of pure functions, which means you know they only take inputs and generate predictable outputs, without performing any I/O effects. The building blocks are reactive streams from libraries like [xstream](http://staltz.com/xstream), [RxJS](http://reactivex.io/rxjs) or [Most.js](https://github.com/cujojs/most/), which greatly simplify code related to events, asynchrony, and errors. Structuring the application with streams also separates concerns, because all [dynamic updates to a piece of data are co-located](/observables.html#reactive-programming) and impossible to change from outside. As a result, apps in Cycle are entirely `this`-less and have nothing comparable to imperative calls such as `setState()` or `update()`.
47 |
48 |
49 |
50 | ## Simple and Concise
51 |
52 | Cycle.js is a framework with very few concepts to learn. The core API has just one function: `run(app, drivers)`. Besides that, there are **streams**, **functions**, **drivers** (plugins for different types of I/O effects), and a helper function to isolate scoped components. This is a framework with very little "magic". Most of the building blocks are just JavaScript functions. Usually the lack of "magic" leads to very verbose code, but since functional reactive streams are able to build complex dataflows with a few operations, you will come to see how apps in Cycle.js are small and readable.
53 |
54 |
55 |
56 | ## Extensible and Testable
57 |
58 | Drivers are plugin-like simple functions that take messages from sinks and call imperative functions. All I/O effects are contained in drivers. This means your application is just a pure function, and it becomes easy to swap drivers around. The community has built drivers for [React Native](https://github.com/cyclejs/cycle-react-native), [HTML5 Notification](https://github.com/cyclejs/cycle-notification-driver), [Socket.io](https://github.com/cgeorg/cycle-socket.io), etc. Sources and sinks can be easily used as [Adapters and Ports](https://iancooper.github.io/Paramore/ControlBus.html). This also means testing is mostly a matter of feeding inputs and inspecting the output. No deep mocking needed. Your application is just a pure transformation of data.
59 |
60 |
61 | ## Explicit dataflow
62 |
63 | In every Cycle.js app, each of the stream declarations is a node in a dataflow graph, and the dependencies between declarations are arrows. This means there is a one-to-one correspondence between your code and *minimap*-like graph of the dataflow between external inputs and external outputs.
64 |
65 |
95 |
96 | In many frameworks the flow of data is *implicit*: you need to build a mental model of how data moves around in your app. In Cycle.js, the flow of data is clear by reading your code.
97 |
98 | ## Composable
99 |
100 | Cycle.js has components, but unlike other frameworks, every single Cycle.js app, no matter how complex, is a function that can be reused in a larger Cycle.js app.
101 |
102 |
103 | {% include /img/nested-components.svg %}
104 |
105 |
106 | Sources and sinks are the interface between the application and the drivers, but they are also the interface between a child component and its parent. Cycle.js components can be simply GUI widgets like in other frameworks, but they are not limited to GUIs only. You can make Web Audio components, network requests components, and others, since the sources/sinks interface is not exclusive to the DOM.
107 |
108 | ## Learn it in 1h 37min
109 |
110 |
111 | {% include /img/egghead.svg %}
112 |
113 |
114 | Got 1 hour and 37 minutes? That is all it takes to learn the essentials of Cycle.js. Watch [**this free Egghead.io video course**](https://egghead.io/series/cycle-js-fundamentals) given by the creator of Cycle.js. Understand Cycle.js from within by following how it is built from scratch, then learn how to transform your ideas into applications.
115 |
116 |
117 |
118 | ## Supports...
119 |
120 | - [**Virtual DOM rendering**](https://github.com/cyclejs/cyclejs/tree/master/dom)
121 | - [**Server-side rendering**](https://github.com/cyclejs/cyclejs/tree/master/examples/isomorphic)
122 | - [**JSX**](http://cycle.js.org/getting-started.html)
123 | - [**TypeScript**](https://github.com/cyclejs/cyclejs/tree/master/examples/bmi-typescript)
124 | - [**React Native**](https://github.com/cyclejs/cycle-react-native)
125 | - [**Time traveling**](https://github.com/cyclejs/cycle-time-travel)
126 | - [**Routing with the History API**](https://github.com/cyclejs/history)
127 | - [**And more...**](https://github.com/cyclejs-community/awesome-cyclejs)
128 |
--------------------------------------------------------------------------------
/_posts/2015-01-31-getting-started.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Getting Started"
3 | tags: chapters
4 | ---
5 |
6 |
Using create-cycle-app
7 |
8 | The quickest way to create a new project with Cycle.js is by using [create-cycle-app](https://github.com/cyclejs-community/create-cycle-app).
9 |
10 | {% highlight text %}
11 | npm install --global create-cycle-app
12 | create-cycle-app my-awesome-app
13 | {% endhighlight %}
14 |
15 | This will create a project called *my-awesome-app* (or the name you choose) with Cycle *Run* and Cycle *DOM*.
16 |
17 |
npm
18 |
19 | If you want to have more control over your project, the recommended channel for downloading Cycle.js as a package is through [npm](http://npmjs.org/). Create a new directory and run this inside that directory:
20 |
21 | {% highlight text %}
22 | npm install xstream @cycle/xstream-run @cycle/dom
23 | {% endhighlight %}
24 |
25 | This installs [xstream](http://staltz.com/xstream), Cycle *Run* using *xstream*, and Cycle *DOM*. Packages *xstream* and *Run* are the minimum required API to work with Cycle.js. The *Run* package includes a single function `run()`, and Cycle *DOM* is the standard DOM Driver providing a way to interface with the DOM. You can also use Cycle.js with other stream libraries like RxJS. Your options are:
26 |
27 | - `npm install xstream @cycle/xstream-run` (recommended if you don't know what to choose)
28 | - `npm install rx @cycle/rx-run` (for [RxJS v4](https://github.com/Reactive-Extensions/RxJS))
29 | - `npm install rxjs @cycle/rxjs-run` (for [RxJS v5+](http://reactivex.io/rxjs))
30 | - `npm install most @cycle/most-run` (for cujo.js [most.js](https://github.com/cujojs/most))
31 |
32 | Packages of the type `@org/package` are [npm scoped packages](https://docs.npmjs.com/getting-started/scoped-packages), supported if your npm installation is version 2.11 or higher. Check your npm version with `npm --version` and upgrade in order to install Cycle.js.
33 |
34 | In case you are not dealing with a DOM-interfacing web application, you can omit `@cycle/dom` when installing.
35 |
36 |
First steps
37 |
38 | We recommend the use of a bundling tool such as [browserify](http://browserify.org/) or [webpack](http://webpack.github.io/), in combination with ES6 (a.k.a. ES2015) through a transpiler (e.g. [Babel](http://babeljs.io/) or [TypeScript](http://typescriptlang.org/)). Most of the code examples in this documentation assume some basic familiarity with ES6. Once your build system is set up, **write your main JavaScript source file like**:
39 |
40 | {% highlight js %}
41 | import xs from 'xstream';
42 | import {run} from '@cycle/xstream-run';
43 | import {makeDOMDriver} from '@cycle/dom';
44 |
45 | // ...
46 | {% endhighlight %}
47 |
48 | The second line imports the function `run(main, drivers)`, where `main` is the entry point for our whole application, and `drivers` is a record of driver functions labeled by some name.
49 |
50 | **Create the `main` function and the `drivers` record:**
51 |
52 | {% highlight js %}
53 | import xs from 'xstream';
54 | import {run} from '@cycle/xstream-run';
55 | import {makeDOMDriver} from '@cycle/dom';
56 |
57 | function main() {
58 | // ...
59 | }
60 |
61 | const drivers = {
62 | DOM: makeDOMDriver('#app')
63 | };
64 |
65 | run(main, drivers);
66 | {% endhighlight %}
67 |
68 | `makeDOMDriver(container)` from Cycle *DOM* returns a driver function to interact with the DOM. This function is registered under the key `DOM` in the `drivers` object above.
69 |
70 | **Send messages from `main` to the `DOM` driver:**
71 |
72 | {% highlight js %}
73 | import xs from 'xstream';
74 | import {run} from '@cycle/xstream-run';
75 | import {makeDOMDriver, h1} from '@cycle/dom';
76 |
77 | function main() {
78 | const sinks = {
79 | DOM: xs.periodic(1000).map(i =>
80 | h1('' + i + ' seconds elapsed')
81 | )
82 | };
83 | return sinks;
84 | }
85 |
86 | const drivers = {
87 | DOM: makeDOMDriver('#app')
88 | };
89 |
90 | run(main, drivers);
91 | {% endhighlight %}
92 |
93 | We have filled the `main()` function with some code: returns an object `sinks` which has an `xstream` stream defined under the name `DOM`. This indicates `main()` is sending the stream as messages to the DOM driver. Sinks are outgoing messages. The stream emits Virtual DOM `
` elements displaying `${i} seconds elapsed` changing over time every second, where `${i}` is replaced by `0`, `1`, `2`, etc.
94 |
95 | **Catch messages from `DOM` into `main` and vice-versa:**
96 |
97 | {% highlight js %}
98 | import xs from 'xstream';
99 | import {run} from '@cycle/xstream-run';
100 | import {makeDOMDriver, div, input, p} from '@cycle/dom';
101 |
102 | function main(sources) {
103 | const sinks = {
104 | DOM: sources.DOM.select('input').events('click')
105 | .map(ev => ev.target.checked)
106 | .startWith(false)
107 | .map(toggled =>
108 | div([
109 | input({attrs: {type: 'checkbox'}}), 'Toggle me',
110 | p(toggled ? 'ON' : 'off')
111 | ])
112 | )
113 | };
114 | return sinks;
115 | }
116 |
117 | const drivers = {
118 | DOM: makeDOMDriver('#app')
119 | };
120 |
121 | run(main, drivers);
122 | {% endhighlight %}
123 |
124 | Function `main()` now takes `sources` as input. Just like the output `sinks`, the input `sources` follow the same structure: an object containing `DOM` as a property. `sources.DOM` is an object with a queryable API to get streams. Use `sources.DOM.select(selector).events(eventType)` to get a stream of `eventType` DOM events happening on the element(s) specified by `selector`. This `main()` function takes the stream of clicks happening on `input` elements, and maps those toggling events to Virtual DOM elements displaying a togglable checkbox.
125 |
126 | We used the `div()`, `input()`, `p()` helper functions to create virtual DOM elements for the respective `
`, ``, `
` DOM elements, but you can also use JSX with Babel. The following only works if you are building with Babel: (1) install the npm packages [babel-plugin-transform-react-jsx](http://babeljs.io/docs/plugins/transform-react-jsx/) and [snabbdom-jsx](https://www.npmjs.com/package/snabbdom-jsx); (2) specify a pragma for JSX as shown in the following example `.babelrc` file:
127 |
128 | {% highlight json %}
129 | {
130 | "presets": [
131 | "es2015"
132 | ],
133 | "plugins": [
134 | "syntax-jsx",
135 | ["transform-react-jsx", {"pragma": "html"}]
136 | ]
137 | }
138 | {% endhighlight %}
139 |
140 | (3) import Snabbdom JSX as `import {html} from 'snabbdom-jsx';`, and then you can utilize JSX:
141 |
142 | {% highlight html %}
143 | import xs from 'xstream';
144 | import {run} from '@cycle/xstream-run';
145 | import {makeDOMDriver} from '@cycle/dom';
146 | import {html} from 'snabbdom-jsx';
147 |
148 | function main(sources) {
149 | const sinks = {
150 | DOM: sources.DOM.select('input').events('click')
151 | .map(ev => ev.target.checked)
152 | .startWith(false)
153 | .map(toggled =>
154 |
155 | Toggle me
156 |
{toggled ? 'ON' : 'off'}
157 |
158 | )
159 | };
160 | return sinks;
161 | }
162 |
163 | const drivers = {
164 | DOM: makeDOMDriver('#app')
165 | };
166 |
167 | run(main, drivers);
168 | {% endhighlight %}
169 |
170 | This example portrays the most common problem-solving pattern in Cycle.js: formulate the computer's behavior as a function of streams: continuously listen to source messages from drivers and continuously provide sinks messages (in our case, Virtual DOM elements) to the drivers. Read the next chapter to get familiar with this pattern.
171 |
172 |
Quick Start
173 |
174 | In the future, you can quickly set up a development and production ready Cycle.js project using the [cyc](https://github.com/edge/cyc) boilerplate.
175 |
176 | It comes with babel transpilation, hot-reloading, and an isomorphic server.
177 |
178 |
Cycle.js as a script
179 |
180 | In the rare occasion you need Cycle.js scripts as standalone JavaScript files, you can download them from [unpkg](https://unpkg.com):
181 |
182 | - Latest Cycle.js [xstream run](https://unpkg.com/@cycle/xstream-run/dist/cycle.js)
183 | - Latest Cycle.js [most.js run](https://unpkg.com/@cycle/most-run/dist/cycle-most-run.js)
184 | - Latest Cycle.js [RxJS v5 run](https://unpkg.com/@cycle/rxjs-run/dist/cycle.js)
185 | - Latest Cycle.js [RxJS v4 run](https://unpkg.com/@cycle/rx-run/dist/cycle.js)
186 | - Latest Cycle.js [DOM](https://unpkg.com/@cycle/dom/dist/cycle-dom.js)
187 | - Latest Cycle.js [HTTP](https://unpkg.com/@cycle/http/dist/cycle-http-driver.js)
188 | - Latest Cycle.js [Isolate](https://unpkg.com/@cycle/isolate/dist/cycle-isolate.js)
189 |
--------------------------------------------------------------------------------
/_includes/img/dataflow-minimap.svg:
--------------------------------------------------------------------------------
1 |
2 |
86 |
--------------------------------------------------------------------------------
/_includes/img/cycle-nested-frontpage.svg:
--------------------------------------------------------------------------------
1 |
2 |
98 |
--------------------------------------------------------------------------------
/_posts/2015-01-29-streams.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Streams"
3 | tags: chapters
4 | redirect_from:
5 | - /observables
6 | ---
7 |
8 | Cycle.js is heavily dependent on reactive and functional streams. One such common example is the Observable from [RxJS](http://reactivex.io/intro.html). The name "Observable" immediately indicates a relation to the [Observer pattern](https://en.wikipedia.org/wiki/Observer_pattern). This pattern is key in many flavors of the [Model-View-Controller](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) architectural pattern for user interfaces. For instance, typically the View observes changes in the Model. In the Observer pattern, this means the Model would be the "Subject" being observed.
9 |
10 | However, an Observable is not exactly the same concept as a traditional Subject from the Observer pattern, because Observables share features with Iterables from the [Iterator pattern](https://en.wikipedia.org/wiki/Iterator_pattern) as well.
11 |
12 | #### Observables are lazy event streams which can emit zero or more events, and may or may not finish.
13 |
14 | Observables originated from [ReactiveX](http://reactivex.io/intro.html), a Reactive Programming library. Reactivity is an important aspect in Cycle.js, and part of the core principles that led to the creation of this framework. There is a lot of confusion surrounding what Reactive means, so let's focus on that topic for a while.
15 |
16 |
Reactive Programming
17 |
18 | Say you have a module Foo and a module Bar. A *module* can be considered to be an object of an [OOP](https://en.wikipedia.org/wiki/Object-oriented_programming) class, or any other mechanism of encapsulating state. Let's assume all code lives in some module. Here we have an arrow from Foo to Bar, indicating that Foo somehow affects state living inside Bar.
19 |
20 |
21 | {% include img/modules-foo-bar.svg %}
22 |
23 |
24 | A practical example of such arrow would be: *whenever Foo does a network request, increment a counter in Bar*. If all code lives in some module, **where does this arrow live?** Where is it defined? The typical choice would be to write code inside Foo which calls a method in Bar to increment the counter.
25 |
26 | {% highlight js %}
27 | // This is inside the Foo module
28 |
29 | function onNetworkRequest() {
30 | // ...
31 | Bar.incrementCounter();
32 | // ...
33 | }
34 | {% endhighlight %}
35 |
36 | Because Foo owns the relationship "*when network request happens, increment counter in Bar*", we say the arrow lives at the arrow tail, i.e., Foo.
37 |
38 |
39 | {% include img/passive-foo-bar.svg %}
40 |
41 |
42 | Bar is **passive**: it allows other modules to change its state. Foo is proactive: it is responsible for making Bar's state function correctly. The passive module is unaware of the existence of the arrow which affects it.
43 |
44 | The alternative to this approach inverts the ownership of the arrow, without inverting the arrow's direction.
45 |
46 |
47 | {% include img/reactive-foo-bar.svg %}
48 |
49 |
50 | With this approach, Bar listens to an event happening in Foo, and manages its own state when that event happens.
51 |
52 | {% highlight js %}
53 | // This is inside the Bar module
54 |
55 | Foo.addOnNetworkRequestListener(() => {
56 | self.incrementCounter(); // self is Bar
57 | });
58 | {% endhighlight %}
59 |
60 | Bar is **reactive**: it is fully responsible for managing its own state by reacting to external events. Foo, on the other hand, is unaware of the existence of the arrow originating from its network request event.
61 |
62 | What is the benefit of this approach? It is Inversion of Control, mainly because Bar is responsible for itself. Plus, we can hide Bar's `incrementCounter()` as a private function. In the passive case, it was required to have `incrementCounter()` public, which means we are exposing Bar's internal state management outwards. It also means if we want to discover how Bar's counter works, we need to find all usages of `incrementCounter()` in the codebase. In this regard, Reactive and Passive seem to be dual to each other.
63 |
64 | | | Passive | Reactive |
65 | |-----------------------|-------------------------|---------------|
66 | | How does Bar work? | *Find usages* | Look inside |
67 |
68 | On the other hand, when applying the Reactive pattern, if you want to discover which modules are affected by an event in a Listenable module, you must find all usages of that event.
69 |
70 | | | Proactive | Listenable |
71 | |-----------------------------|-------------------------|---------------|
72 | | Which modules are affected? | Look inside | *Find Usages* |
73 |
74 | Passive/Proactive programming has been the default way of working for most programmers in imperative languages. Sometimes the Reactive pattern is used, but sporadically. The selling point for widespread Reactive programming is to build self-responsible modules which focus on their own functionality rather than changing external state. This leads to Separation of Concerns.
75 |
76 | The challenge with Reactive programming is this paradigm shift where we attempt to choose the Reactive/Listenable approach by default, before considering Passive/Proactive. After rewiring your brain to think Reactive-first, the learning curve flattens and most tasks become straightforward, especially when using a Reactive library like RxJS or *xstream*.
77 |
78 |
Streams in xstream
79 |
80 | Reactive programming can be implemented with: event listeners, [RxJS](http://reactivex.io/rxjs), [Bacon.js](http://baconjs.github.io/), [Kefir](https://rpominov.github.io/kefir/), [most.js](https://github.com/cujojs/most), [EventEmitter](https://nodejs.org/api/events.html), [Actors](https://en.wikipedia.org/wiki/Actor_model), and more. Even [spreadsheets](https://en.wikipedia.org/wiki/Reactive_programming) utilize the same idea of the cell formula defined at the arrow head. The above definition of Reactive programming is not limited to streams, and does not conflict with previous definitions of Reactive Programming. Cycle.js supports multiple stream libraries, such as [RxJS v4](https://github.com/Reactive-Extensions/RxJS), [RxJS v5](http://reactivex.io/rxjs), [xstream](http://staltz.com/xstream), and [most.js](https://github.com/cujojs/most), but by default we choose *xstream* because it was custom built for Cycle.js.
81 |
82 | In short, a *Stream* in *xstream* is an event stream which can emit zero or more events, and may or may not finish. If it finishes, then it does so by either emitting an error or a special "complete" event.
83 |
84 | {% highlight text %}
85 | Stream contract: (next)* (complete|error){0,1}
86 | {% endhighlight %}
87 |
88 | As an example, here is a typical Stream: it emits some events, then it eventually completes.
89 |
90 |
91 | {% include img/completed-stream.svg %}
92 |
93 |
94 | Streams can be listened to, just like EventEmitters and DOM events can.
95 |
96 | {% highlight js %}
97 | myStream.addListener({
98 | next: function handleNextEvent(event) {
99 | // do something with `event`
100 | },
101 | error: function handleError(error) {
102 | // do something with `error`
103 | },
104 | complete: function handleCompleted() {
105 | // do something when it completes
106 | },
107 | });
108 | {% endhighlight %}
109 |
110 | Notice there are 3 handlers: one for events, one for errors, and one for "complete".
111 |
112 | *xstream* Streams become very useful when you transform them with the so-called *operators*, pure functions that create new Streams on top of existing ones. Given a Stream of click events, you can easily make a Stream of the number of times the user clicked.
113 |
114 | {% highlight js %}
115 | const clickCountStream = clickStream
116 | // each click represents "1 amount"
117 | .mapTo(1)
118 | // sum all events `1` over time, starting from 0
119 | .fold((count, x) => count + x, 0);
120 | {% endhighlight %}
121 |
122 | [Succinctness is Power](http://www.paulgraham.com/power.html), and *xstream* operators demonstrate that you can achieve a lot with a few well-placed operators. With only about [26 operators](https://github.com/staltz/xstream#methods-and-operators), you can build almost all programming patterns needed in a Cycle.js app.
123 |
124 | Knowing the basics of reactive streams programming is a prerequisite to getting work done with Cycle.js. Instead of teaching RxJS or *xstream* on this site, we recommend a few great learning resources, in case you need to learn more. *xstream* is similar to *RxJS*, so these resources apply:
125 |
126 | - [The introduction to Reactive Programming you've been missing](https://gist.github.com/staltz/868e7e9bc2a7b8c1f754): a thorough introduction to RxJS by Cycle.js author Andre Staltz.
127 | - [Introduction to Rx](http://introtorx.com/): an online book focused on Rx.NET, but most concepts map directly to RxJS.
128 | - [ReactiveX.io](http://reactivex.io/): official cross-language documentation site for ReactiveX.
129 | - [Learn Rx](http://reactivex.io/learnrx/): an interactive tutorial with arrays and Observables, by Jafar Husain.
130 | - [RxJS lessons at Egghead.io](https://egghead.io/technologies/rx)
131 | - [RxJS GitBook](http://xgrommx.github.io/rx-book/)
132 | - [RxMarbles](http://rxmarbles.com/): interactive diagrams of RxJS operators, built with Cycle.js.
133 | - [Async JavaScript at Netflix](https://www.youtube.com/watch?v=XRYN2xt11Ek): video of Jafar Husain introducing RxJS.
134 |
135 |
Streams in Cycle.js
136 |
137 | Now we are able to explain the types of `senses` and `actuators`, and what it means for the computer and human to be "mutually observed."
138 |
139 | In the simplest case, the computer generates pixels on the screen, and the human generates mouse and keyboard events. The computer observes these user inputs and the human observes the screen state generated by the computer. Notice that we can model each of these as *Streams*:
140 |
141 | - Computer's output: a stream of screen images.
142 | - Human's output: a stream of mouse/keyboard events.
143 |
144 | The `computer()` function takes the human's output as its input, and vice versa. They mutually observe each other's output. In JavaScript, we could write the computer function as a simple chain of *xstream* transformations on the input stream.
145 |
146 | {% highlight js %}
147 | function computer(userEventsStream) {
148 | return userEventsStream
149 | .map(event => /* ... */)
150 | .filter(someCondition)
151 | .map(transformItToScreenPixels)
152 | .flatten();
153 | }
154 | {% endhighlight %}
155 |
156 | While doing the same with the `human()` function would be elegant, we cannot do that as a simple chain of operators because we need to leave the JavaScript environment and affect the external world. While conceptually the `human()` function can exist, in practice, we need to use *driver* functions in order to reach the external world.
157 |
158 | [Drivers](/drivers.html) are adapters to the external world, and each driver represents one aspect of external effects. For instance, the DOM Driver takes a "screen" Stream generated by the computer, and returns Streams of mouse and keyboard events. In between, the DOM Driver function produces "*write*" side effects to render elements on the DOM, and catches "*read*" side effects to detect user interaction. This way, the DOM Driver function can act on behalf of the user. The name "driver" is based off Operating System drivers, which have a similar kind of role: to create a bridge between devices and your software.
159 |
160 | Joining both parts, we have a computer function, often called `main()`, and a driver function, where the output of one is the input of the other.
161 |
162 | {% highlight text %}
163 | y = domDriver(x)
164 | x = main(y)
165 | {% endhighlight %}
166 |
167 | The circular dependency above cannot be solved if `=` means assignment, because that would be equivalent to the command `x = g(f(x))`, and `x` is undefined on the right-hand side.
168 |
169 | This is where Cycle.js comes in: you only need to specify `main()` and `domDriver()`, and give it to the Cycle.js `run()` command which connects them circularly.
170 |
171 | {% highlight js %}
172 | function main(sources) {
173 | const sinks = {
174 | DOM: // transform sources.DOM through
175 | // a series of xstream operators
176 | };
177 | return sinks;
178 | }
179 |
180 | const drivers = {
181 | DOM: makeDOMDriver('#app') // a Cycle.js helper factory
182 | };
183 |
184 | run(main, drivers); // solve the circular dependency
185 | {% endhighlight %}
186 |
187 | This is how the name "*Cycle.js*" came to be. It is a framework that solves the cyclic dependency of Observables which emerge during dialogues (mutual observations) between the Human and the Computer.
188 |
189 | >
Is Cycle.js a framework?
190 | >
191 | > The Cycle `run()` function is implemented in about 200 lines of code. It's a very small library.
192 | >
193 | > In the TodoMVC built with Cycle.js, these are the proportions of code each library or section comprises:
194 | >
195 | > - snabbdom (Virtual DOM library): 39.1 kB
196 | > - @cycle/dom: 28.9 kB
197 | > - xstream: 22.2 kB
198 | > - TodoMVC src: 15.3 kB
199 | > - @cycle/xstream-run: 4 kB
200 | > - misc: 59.5 kB
201 | >
202 | > Notice how small `@cycle/xstream-run` is. Cycle.js is simply an architecture for building reactive web applications: a set of ideas about how you should structure your app using *xstream* or *RxJS* or *most.js*. To help you out, it also provides some libraries to address common use cases: Cycle *DOM*, to help interact with the DOM, and Cycle run functions, to help create loops between the program and the drivers.
203 |
204 | Next, read the [basic examples](/basic-examples.html) which apply what we've learned so far about Cycle.js.
205 |
--------------------------------------------------------------------------------
/_posts/2015-01-23-drivers.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Drivers"
3 | tags: chapters
4 | ---
5 |
6 | Throughout this documentation site we have extensively used *drivers*. The DOM Driver has been the most common one, but also the HTTP driver was used.
7 |
8 | What are drivers and when should you use them? When should you create your own driver, and how do they work? These are a few questions we will address in this chapter.
9 |
10 | #### Drivers are functions that listen to sink streams (their input), perform imperative side effects, and may return source streams (their output).
11 |
12 | They are meant for encapsulating imperative side effects in JavaScript. The rule of thumb is: whenever you have a JavaScript function such as `doSomething()` which returns nothing, it should be contained in a driver.
13 |
14 | Let's study what drivers do by analyzing the most common one: the DOM Driver.
15 |
16 | >
Why the name "driver"?
17 | >
18 | > In Haskell 1.0 Stream I/O, similar in nature to Cycle.js, there is a cyclic interaction between the program's `main` function and Haskell's `os` function. In operating systems, drivers are software interfaces to use some hardware devices, which incur side effects in the external world.
19 | >
20 | > In Cycle.js, one can consider the "operating system" to be the execution environment surrounding your application. Roughly speaking, the DOM, the console, JavaScript and JS APIs assume the role of the operating system for the web. We need *software adapters* to interface with the browser and other environments such as Node.js. Cycle.js drivers are there as adapters between the external world (including the user and the JavaScript execution environment) and the application world built with Cycle.js tools.
21 |
22 |
DOM Driver
23 |
24 | The DOM Driver is the most important and most common driver in Cycle.js. When building interactive web apps, it is probably the most important tool in Cycle.js. In fact, while Cycle *Run* function is only about 200 lines of code, Cycle *DOM* is at least 4 times larger.
25 |
26 | It's main purpose is to be a proxy to the user using the browser. Conceptually we would like to work assuming the existence of a `human()` function, as this diagram reminds us:
27 |
28 |
29 | {% include /img/human-computer-diagram.svg %}
30 |
31 |
32 | However, in practice, we write our `main()` function targeted at a `domDriver()`. For a user interacting with a browser, we only need to make our `main()` interact with the DOM. Whenever we need to show something to the user, we instead show that to the DOM, and the DOM together with the browser shows that to our user. When we need to detect the user's interaction events, we attach event listeners on the DOM, and the DOM will notify us when the user interacts with the browser on the computer.
33 |
34 |
35 | {% include /img/main-domdriver-side-effects.svg %}
36 |
37 |
38 | Notice there are two directions of interaction with the external world through the DOM. The *write* effect is the renderization of our Snabbdom VNodes to DOM elements which can be shown on the user's screen. The *read* effect is the detection of DOM events generated by the user manipulating the computer.
39 |
40 | The `domDriver()` manages these two effects while allowing them to be interfaced with the `main()`. The *input* to `domDriver()` captures instructions for the *write* effect, and the *read* effect is exposed as the *output* of `domDriver()`. The anatomy of the `domDriver()` function is roughly the following:
41 |
42 | {% highlight js %}
43 | function domDriver(vdom$) {
44 | // Use vdom$ as instructions to create DOM elements
45 | // ...
46 | return {
47 | select: function select(selector) {
48 | // returns an object with two functions: `events()`
49 | // and `elements()`. Function `events(eventType)`
50 | // returns the stream of `eventType` DOM events
51 | // happening on the elements matched by `selector`.
52 | // Function `elements()` is the stream of DOM
53 | // elements matching the given `selector`.
54 | }
55 | };
56 | }
57 | {% endhighlight %}
58 |
59 | The input `vdom$` is the output from `main()`, and the output of `domDriver()` is the input to `main()`:
60 |
61 | {% highlight js %}
62 | function main(sources) {
63 | // Use sources.DOM.select(selector).events(eventType)
64 | // ...
65 | // Create vdom$ somehow
66 | // ...
67 | return {
68 | DOM: vdom$
69 | };
70 | }
71 | {% endhighlight %}
72 |
73 | As a recap:
74 |
75 | - `main()`: takes **sources** as input, returns **sinks**
76 | - `domDriver()`: takes **sinks** as input, performs write and read effects, returns **sources**.
77 |
78 |
Isolating side effects
79 |
80 | Drivers should always be associated with some side effect. As we saw, even though the DOM Driver's main purpose is to represent the user, it has write and read effects.
81 |
82 | In JavaScript, nothing stops you from writing your `main()` function with side effects. A simple `console.log()` is already a side effect. However, to keep `main()` pure and reap its benefits like testability and predictability, it is better to encapsulate all side effects in drivers.
83 |
84 | Imagine, for instance, a driver for network requests. By isolating the network request side effect, your application's `main()` function can focus on business logic related to the app's behavior, and not on lower-level instructions to interface with external resources. This also allows a simple method for testing network requests: you can replace the actual network driver with a fake network driver. It just needs to be a function that mimics the network driver function, and makes assertions.
85 |
86 | Avoid making drivers if they do not have effects to the external world somehow. Especially do not create drivers to contain business logic. This is most likely a code smell.
87 |
88 | Drivers should focus solely on being an interface for effects, and usually are libraries that simply enable your Cycle.js app to perform different effects. Sometimes, though, a one-liner driver can be created on the fly instead of being a library, for instance this simple logging driver:
89 |
90 | {% highlight js %}
91 | run(main, {
92 | log: msg$ => { msg$.addListener({next: msg => console.log(msg)}) }
93 | });
94 | {% endhighlight %}
95 |
96 |
Read-only and write-only drivers
97 |
98 | Most drivers, like the DOM Driver, take *sinks* (to describe a *write*) and return *sources* (to catch *reads*). However, we might have valid cases for write-only drivers and read-only drivers.
99 |
100 | For instance, the one-liner `log` driver we just saw above is a write-only driver. Notice how it is a function that does not return any stream, it simply consumes the sink `msg$` it receives.
101 |
102 | Other drivers only create source streams that emit events to the `main()`, but don't take in any `sink` from `main()`. An example of such would be a read-only Web Socket driver, drafted below:
103 |
104 | {% highlight js %}
105 | function WSDriver(/* no sinks */) {
106 | return xs.create({
107 | start: listener => {
108 | this.connection = new WebSocket('ws://localhost:4000');
109 | connection.onerror = (err) => {
110 | listener.error(err)
111 | }
112 | connection.onmessage = (msg) => {
113 | listener.next(msg)
114 | }
115 | },
116 | stop: () => {
117 | this.connection.close();
118 | },
119 | });
120 | }
121 | {% endhighlight %}
122 |
123 |
How to make drivers
124 |
125 | You should only be reading this section if you have clear intentions to make a driver and expose it as a library (unless it's a one-liner driver). Typically, when writing a Cycle.js app, you do not need to create your own drivers.
126 |
127 | Consider first carefully which side effects your driver is responsible for. And can it have both read and write effects?
128 |
129 | Once you map out the read/write effects, consider how diverse those can be. Create an empathic API which covers the common cases elegantly.
130 |
131 | The **input** to the driver function is expected to be a single stream. This is a practical API for the app developer to use when returning the `sinks` object in `main()`. Notice how the DOM Driver takes a single `vdom$` stream as input, and how sophisticated and expressive VNodes from Snabbdom can be. On the other hand, don't always choose JavaScript objects as the values emitted in the Observable. Use objects when they make sense, and remember to keep the API simple rather than overly-generic. Don't over-engineer.
132 |
133 | As a second, optional, argument to the driver function, you can expect `runStreamAdapter`. A "Stream Adapter" is a library that knows how to convert between one specific stream library (like xstream or RxJS) to a generic adapter interface used internally in Cycle.js. This is needed for those cases your driver function needs to return a sophisticated source object which can create arbitrary streams using the same stream library that your application uses. If your app uses `@cycle/xstream-run`, then it uses under the hood `@cycle/xstream-adapter`, which is the argument `runStreamAdapter` given to drivers. If your app uses `@cycle/rxjs-run`, then `runStreamAdapter` is `@cycle/rxjs-adapter`, and so forth. Hence the driver function signature is:
134 |
135 | {% highlight js %}
136 | function myDriver(sink$, runStreamAdapter /* optional */)
137 | {% endhighlight %}
138 |
139 | The **output** of the driver function can either be a single stream or a *queryable collection* of streams.
140 |
141 | In the case of a single stream as output source, depending on how diverse the values emitted by this stream are, you might want to make those values easily filterable (using the xstream or RxJS `filter()` operator). Design an API which makes it easy to filter the stream, keeping in mind what was provided as the sink stream to the driver function.
142 |
143 | In some cases it is necessary to output a queryable collection of Observables, instead of a single one. A **queryable collection of Observables** is essentially a JavaScript object with a function used to choose a particular stream based on a parameter, e.g. `get(param)`.
144 |
145 | The DOM Driver, for instance, outputs a queryable collection of streams. The collection is in fact lazy: none of the streams outputted by `select(selector).events(eventType)` existed prior to the call of `events()`. This is because we cannot afford creating streams for *all* possible events on *all* elements on the DOM. Take inspiration from the lazy queryable collection of streams from the DOM Driver whenever the output source contains a large (possibly infinite) amount of streams.
146 |
147 | You most likely will need `runStreamAdapter` only for queryable collections of streams **and** if you want your driver usable by any other stream library. If you are building your driver only for your own use, then just write the driver using the same stream library that your application uses.
148 |
149 |
Example driver implementation
150 |
151 | Suppose you have a fake real-time channel API called `Sock`. It is able to connect to a remote peer, send messages, and receive push-based messages. The API for `Sock` is:
152 |
153 | {% highlight js %}
154 | // Establish a connection to the peer
155 | let sock = new Sock('unique-identifier-of-the-peer');
156 |
157 | // Subscribe to messages received from the peer
158 | sock.onReceive(function (msg) {
159 | console.log('Received message: ' + msg);
160 | });
161 |
162 | // Send a single message to the peer
163 | sock.send('Hello world');
164 | {% endhighlight %}
165 |
166 | **How do we build a driver for `Sock`?** We start by identifying the effects. The *write* effect is `sock.send(msg)` and the *read* effect is the listener for received messages. Our `sockDriver(sink)` should take `sink` as instructions to perform the `send(msg)` calls. The output from `sockDriver()` should be `source`, containing all received messages.
167 |
168 | Since both input and output should be streams, it's easy to see `sink` in `sockDriver(sink)` should be a stream of outgoing messages to the peer. And conversely, the source should be a stream of incoming messages. This is a draft of our driver function:
169 |
170 | {% highlight js %}
171 | function sockDriver(outgoing$) {
172 | outgoing$.addListener({
173 | next: outgoing => {
174 | sock.send(outgoing);
175 | },
176 | error: () => {},
177 | complete: () => {},
178 | });
179 |
180 | return xs.create({
181 | start: listener => {
182 | sock.onReceive(function (msg) {
183 | listener.next(msg);
184 | });
185 | },
186 | stop: () => {},
187 | });
188 | }
189 | {% endhighlight %}
190 |
191 | The listener of `outgoing$` performs the `send()` side effect, and the stream returned based on `sock.onReceive` takes data from the external world. However, `sockDriver` is assuming `sock` to be available in the closure. As we saw, `sock` needs to be created with a constructor `new Sock()`. To solve this dependency, we need to create a factory that makes `sockDriver()` functions.
192 |
193 | {% highlight js %}
194 | function makeSockDriver(peerId) {
195 | let sock = new Sock(peerId);
196 |
197 | function sockDriver(outgoing$) {
198 | outgoing$.addListener({
199 | next: outgoing => {
200 | sock.send(outgoing));
201 | },
202 | error: () => {},
203 | complete: () => {},
204 | });
205 |
206 | return xs.create({
207 | start: listener => {
208 | sock.onReceive(function (msg) {
209 | listener.next(msg);
210 | });
211 | },
212 | stop: () => {},
213 | });
214 | }
215 |
216 | return sockDriver;
217 | }
218 | {% endhighlight %}
219 |
220 | `makeSockDriver(peerId)` creates the `sock` instance, and returns the `sockDriver()` function. We use this in a Cycle.js app as such:
221 |
222 | {% highlight js %}
223 | function main(sources) {
224 | const incoming$ = sources.sock;
225 | // Create outgoing$ (stream of string messages)
226 | // ...
227 | return {
228 | sock: outgoing$
229 | };
230 | }
231 |
232 | run(main, {
233 | sock: makeSockDriver('B23A79D5-some-unique-id-F2930')
234 | });
235 | {% endhighlight %}
236 |
237 | Notice we have the `peerId` specified when the driver is created in `makeSockDriver(peerId)`. If the `main()` needs to dynamically connect to different peers according to some logic, then we shouldn't use this API anymore. Instead, we need the driver function to take instructions as input, such as "connect to peerId", or "send message to peerId". This is one example of the considerations you should take when designing a driver API.
238 |
239 |
Drivers make Cycle.js extensible
240 |
241 | Cycle *Core* is a very small framework, and Cycle *DOM*'s Driver is available as an optional plugin for your app. This means it is simple to replace the DOM Driver with any other driver function providing interaction with the user.
242 |
243 | You can for instance fork the DOM Driver, adapt it to your preferences, and use it in a Cycle.js app. You can create a driver to interface with sockets. Drivers to perform network requests. Drivers meant for Node.js. Drivers that target other UI trees, such as `
8 |