You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This library provides the ability to define reactive data flows by modeling application state as a directed graph and using [topological sorting](https://en.wikipedia.org/wiki/Topological_sorting) to compute the order in which changes should be propagated.
This library is built on top of <ahref="https://github.com/datavis-tech/reactive-property">reactive-property</a> and <ahref="https://github.com/datavis-tech/graph-data-structure">graph-data-structure</a>
15
+
</p>
14
16
15
-
Require it in your code like this:
17
+
**Table of Contents**
16
18
17
-
```javascript
18
-
var ReactiveFunction =require("reactive-function");
This library is designed to work with [reactive-property](https://github.com/datavis-tech/reactive-property), you'll need that too.
22
-
23
-
```javascript
24
-
var ReactiveProperty =require("reactive-property");
25
-
```
28
+
## Examples
26
29
30
+
### Full Name
27
31
Suppose you have two reactive properties to represent someone's first and last name.
28
32
29
33
```javascript
30
34
var firstName =ReactiveProperty("Jane");
31
35
var lastName =ReactiveProperty("Smith");
32
36
```
33
37
34
-
Suppose you'd like to have another property that represents the full name of the person.
38
+
Another reactive property can represent the full name of the person.
35
39
36
40
```javascript
37
41
var fullName =ReactiveProperty();
@@ -43,12 +47,10 @@ You could set the full name value like this.
43
47
fullName(firstName() +""+lastName());
44
48
```
45
49
46
-
However, this sets the value of `fullName` only once, and it does not get updated when `firstName` or `lastName` change.
47
-
48
-
Here's how you can define a reactive function that updates the full name whenever the first name or last name changes.
50
+
However, the above code sets the value of `fullName` only once. Here's how you can define a **[ReactiveFunction](#constructor)** that automatically updates `fullName` whenever `firstName` or `lastName` change.
49
51
50
52
```javascript
51
-
ReactiveFunction({
53
+
var reactiveFunction =ReactiveFunction({
52
54
inputs: [firstName, lastName],
53
55
output: fullName,
54
56
callback:function (first, last){
@@ -57,33 +59,168 @@ ReactiveFunction({
57
59
});
58
60
```
59
61
60
-
This defines a "reactive function" that will be invoked when its inputs (`firstName` and `lastName`) are both defined and whenever either one changes ([`null` is considered a defined value](https://github.com/datavis-tech/reactive-function/issues/1)). The function will be invoked on the next tick of the JavaScript event loop after it is defined and after any dependencies change.
To force a synchronous evaluation of all reactive functions whose dependencies have updated, you can call
68
+
Whenever `firstName` or `lastName` change, the callback defined above will be executed on the next animation frame. If you don't want to wait until the next animation frame, you can force a synchronous evaluation of the data flow graph by invoking **[digest](#digest)**.
63
69
64
70
```javascript
65
71
ReactiveFunction.digest();
66
72
```
67
73
68
-
Now you can access the computed value of the reactive function by invoking it as a getter.
74
+
Now you can access the computed `fullName` value by invoking it as a getter.
69
75
70
76
```javascript
71
77
console.log(fullName()); // Prints "Jane Smith"
72
78
```
73
79
80
+
### ABC
81
+
82
+
The output of one reactive function can be used as an input to another.
This is the case where [Model.js](https://github.com/curran/model) fails because it uses [Breadth-first Search](https://en.wikipedia.org/wiki/Breadth-first_search) to propagate changes. In this graph, propagation using breadth-first search would cause `e` to be set twice, and the first time it would be set with an *inconsistent state*. This fundamental flaw cropped up as flashes of inconstistent states in some interactive visualizations built on Model.js. For example, it happens when you change the X column in this [Magic Heat Map](http://bl.ocks.org/curran/a54fc3a6578efcdc19f4). This flaw in Model.js is the main inspiration for making this library and using [topological sort](https://en.wikipedia.org/wiki/Topological_sorting), which is the correct algorithm for propagating data flows and avoiding inconsistent states.
Construct a new reactive function. The *options* argument should have the following properties.
173
+
174
+
**inputs* - The input properties. An array of **[ReactiveProperty](https://github.com/datavis-tech/reactive-property#constructor)** instances.
175
+
**output* (optional) - The output property. An instance of **[ReactiveProperty](https://github.com/datavis-tech/reactive-property#constructor)**.
176
+
**callback* - The reactive function callback. Arguments are values of *inputs*. The return value will be assigned to *output*.
177
+
178
+
This constructor sets up a reactive function such that *callback* be invoked
179
+
180
+
* when all input properties are defined,
181
+
* after any input properties change,
182
+
* during a **[digest](#digest)**.
183
+
184
+
An input property is considered "defined" if it has any value other than `undefined`. The special value `null` is considered to be defined.
185
+
186
+
An input property is considered "changed" when
187
+
188
+
* the reactive function is initially set up, and
189
+
* whenever its value is set.
190
+
191
+
Input properties for one reactive function may also be outputs of another.
Propagates changes from input properties through the data flow graph defined by all reactive properties using [topological sorting](https://en.wikipedia.org/wiki/Topological_sorting). An edge in the data flow graph corresponds to a case where the output of one reactive function is used as an input to another.
202
+
203
+
Whenever any input properties for any reactive function change, **[digest](#digest)** is debounced (scheduled for invocation) on the **[nextFrame](#next-frame)**. Because it is debounced, multiple synchronous changes to input properties collapse into a single digest invocation.
204
+
205
+
Digests are debounced to the next animation frame rather than the next tick because browsers will render the page at most every animation frame (approximately 60 frames per second). This means that if DOM manipulations are triggered by reactive functions, and input properties are changed more frequently than 60 times per second (e.g. mouse or keyboard events), the DOM manipulations will only occur at most 60 times per second, not more than that.
Schedules the given function to execute on the next animation frame or next tick.
210
+
211
+
This is a simple polyfill for [requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame) that falls back to [setTimeout](https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers/setTimeout). The main reason for having this is for use in the [tests](https://github.com/datavis-tech/reactive-function/blob/master/test.js), which run in a Node.js environment where `requestAnimationFrame` is not available. Automatic digests are debounced against this function.
Thanks to Mike Bostock and Vadim Ogievetsky for suggesting to have the ability to digest within a single tick of the event loop (the main difference between this project and the original [model-js](https://github.com/curran/model)). This idea has inspired the construction of this library, which I hope will provide a solid foundation for complex interactive visualization systems.
0 commit comments