Learn Derivable in two minutes

Derivable is a library which allows you to define reactive computations.

It has three simple concepts: atoms, derivations & reactions.

Atoms

Atoms model mutable cells. They wrap values and provide methods for reading current values and writing new values:

import {atom} from 'derivable'
let val = atom(42)
val.get() // returns 42
val.set(21)
val.get() // returns 21

At first, get() and set() methods look like overhead: one can simply use a regular JavaScript variable instead. There are advantages though.

First, such an explicit API is good cause state mutations can be easily located while reading a piece of code and thus making the code itself more easier to comprehend and refactor.

Second, and this is the most important point, using Derivable allows efficient derivations and reactions. These things are harder to achieve when using regular JavaScript variables.

Derivations

Derivations are formulas for computations which use other derivations (or atoms) as its input. They are defined with pure functions:

import {derivation} from 'derivable'
let valPlusOne = derivation(() => val.get() + 1)

The fact that valPlusOne calls val.get() makes derivation dependent on val.

You can read the current derivation value with the get() method but the only way to update the derivation value is to update atoms which were used as inputs in the derivation function:

valPlusOne.get() // returns 22
val.set(33)
valPlusOne.get() // returns 34

Derivable makes an important optimisation for derivations: derivations are only recomputed when any of the input values change. This means that calling the get() method several times in a row executes the derivation function at most once (only if the current value is stale):

valPlusOne = derivation(() => {
  console.log('computing') // DON'T DO THAT in real code:
                           // This is just for illustration purposes    
  return val.get() + 1
})
valPlusOne.get() // prints 'computing', returns 34
valPlusOne.get() // just returns 34

This is why it is important for derivations to be pure functions and don’t produce or rely on side effects.

Reactions

Side-effects are still desirable in any real world application, this is why there are reactions.

Reactions are effects attached to derivations (or atoms) which are executed when the value of a derivation changes.

valPlusOne.react(value => {
  console.log('val + 1 = ', value)
})

Now each time valPlusOne updates its value is printed on the console:

val.set(6)

The line above triggers recomputation of the valPlusOne derivation which in turn triggers the reaction above which prints val + 1 = 7 on the console.

Reactions are useful as a bridge from pure state computations to the real world. For example, they can be used to update a piece of UI in response to a computation value change, or log changes to a console, or sync two databases over the network.

Conclusion

We explored the basics of Derivable and learned about atoms, derivations & reactions. You can now go and try to describe your application domain model using these concepts.

The next step is too see what useful and powerful reactions we could define to build real world applications with Derivable.

Now learn how to start using Derivable with React.