re-frame/docs/ApplicationState.md

Application State

Let's understand how re-frame manages application state.

Table Of Contents

• On Data
• The Big Ratom
• The Benefits Of Data-In-The-One-Place

On Data

Well-formed Data at rest is as close to perfection in programming as it gets. All the crap that had to happen to put it there however...

— Fogus (@fogus) April 11, 2014

The Big Ratom

re-frame puts all your application state into one place, which is called app-db.

Ideally, you will provide a spec for this data-in-the-one-place, using a powerful and leveragable schema.

Now, this advice is not the slightest bit controversial for 'real' databases, right? You'd happily put all your well-formed data into PostgreSQL.

But within a running application (in memory), there can be hesitation. If you have a background in OO, this data-in-one-place business is a really, really hard one to swallow. You've spent your life breaking systems into pieces, organised around behaviour and trying to hide state. I still wake up in a sweat some nights thinking about all that Clojure data lying around exposed and passive.

But, as Fogus reminds us, data at rest is quite perfect.

In re-frame's reference implementation, app-db is one of these:

(def app-db  (reagent/atom {}))    ;; a Reagent atom, containing a map

Although it is a Reagent atom (hereafter ratom), I'd encourage you to think of it as an in-memory database. It will contain structured data. You will need to query that data. You will perform CRUD and other transformations on it. You'll often want to transact on this database atomically, etc. So "in-memory database" seems a more useful paradigm than plain old map-in-atom.

Further Notes:

1. app-state would probably be a more accurate name, but I choose app-db instead because I wanted to convey the database notion as strongly as possible.
2. In the documentation and code, I make a distinction between app-db (the ratom) and db which is the (map) value currently stored inside this ratom. Be aware of that naming.
3. the reference implementation creates and manages an app-db for you, so you don't need to declare one yourself (see the 1st FAQ if you want to inspect the value it holds).
4. app-db doesn't actually have to be a ratom containing a map. It could, for example, be a [datascript](https://github.com/tonsky/datascript database). In fact, any database which can signal you when it changes would do. We'd love! to be using [datascript](https://github.com/tonsky/datascript database) - so damn cool - but we had too much data in our apps. If you were to use it, you'd have to tweak the reference implementation a bit and use Posh.

The Benefits Of Data-In-The-One-Place

1. Here's the big one: because there is a single source of truth, we write no code to synchronize state between many different stateful components. I cannot stress too much how significant this is. You end up writing less code and an entire class of bugs is eliminated. (This mindset very different to OO which involves distributing state across objects, and then ensuring that state is synchronized, all the while trying to hide it, which is, when you think about it, quite crazy ... and I did it for years).

2. Because all app state is coalesced into one atom, it can be updated with a single reset!, which acts like a transactional commit. There is an instant in which the app goes from one state to the next, never a series of incremental steps which can leave the app in a temporarily inconsistent, intermediate state. Again, this simplicity causes a certain class of bugs or design problems to evaporate.

3. The data in app-db can be given a strong schema so that, at any moment, we can validate all the data in the application. All of it! We do this check after every single "event handler" runs (event handlers compute new state). And this enables us to catch errors early (and accurately). It increases confidence in the way that Types can increase confidence, only a good schema can provide more leverage than types.

4. Undo/Redo becomes straight forward to implement. It is easy to snapshot and restore one central value. Immutable data structures have a feature called structural sharing which means it doesn't cost much RAM to keep the last, say, 200
   snapshots. All very efficient. For certain categories of applications (eg: drawing applications) this feature is borderline magic. Instead of undo/redo being hard, disruptive and error prone, it becomes virtually trivial. But, many web applications are not self contained data-wise and, instead, are dominated by data sourced from an authoritative remote database. For these applications, re-frame's app-db is mostly a local caching point, and being able to do undo/redo its state is meaningless because the authoritative source of data is elsewhere.

5. The ability to genuinely model control via FSMs (discussed later)

6. The ability to do time travel debugging, even in a production setting. More soon.