A note on terminology: There are a lot of things with similar meanings/use-cases around: subscriptions, reactions, derived atoms, view models.
I'll introduce another to make things even worse: derivative. A derivative implements IWatchable and it's value is the result of applying a function to the value of other things (sources) implementing IWatchable. Whenever any of the sources change the value if the derivative is updated.
Let's assume you're hooked about the idea of storing all your application state in a single atom (db). (Why this is a great idea is covered elsewhere.)
Most of your components don't need the entirety of this state and instead receive a small selection of it that is enough to allow the components to do their job. Now that data is not always a subtree (i.e. (get-in db ...)) but might be a combination of various parts of your state. To transform the data in a way that it becomes useful for components you can use a function: (f @db).
Now you want to re-render your application whenever db changes so the views are representing the data in db. You end up calling f a lot, and remember, f has to do all the transformation for all components that could be rendered on the page, pretty inefficient!
To optimise we can create derivatives that contain data in shapes ideal to specific components and re-render those components when the derivative supplying the data changes.
These derivatives may depend on other derivatives, all ultimately leading up to your single db atom. To keep things efficient we only recalculate the value of a derivative when any of it's sources changes.
The intention of this library is to make the creation and usage of these interdependent references (derivatives) simple and efficient.
A secondary objective is also to achieve the above without relying on global state being defined at the namespace level of this library. (See re-frame vs. pure-frame.)
- transform
dbinto shapes suited for rendering (a.k.a. view models) - managing a pool of derivatives so only needed derivatives are created and freed as soon as they become unused (currently Rum specific)
- server-side rendering (to some degree)
- Ensuring the required data is in
db(server/client rendering)
Derivatives of your application state can be defined via a kind of specification like the one below:
(def db-atom (atom 0))
{
;; a source with no dependencies
:db [[] your-db-atom]
;; a derivative with a dependency
:inc [[:db] (fn [db] (inc db))]
;; a derivative with multiple dependencies
:map [[:db :inc] (fn [db inc] {:db db :inc inc})]
}A specification like the above can be easily turned into a map with the same keys where the values are derivatives (see derivatives.core/build).
Also it can be turned into a registry that can help with only creating needed derivatives and freeing them up when they become unused (see derivatives.core/subman).
Plain rum.core/derived-atom
Rum's derived-atoms serve as building block in this library but there are some things which are (rightfully) not solved by derived-atoms:
- Creation of interdependent derivative chains and
- a mechanism to only create actually needed derived-atoms.
A small code sample should illustrate this well:
(def *db (atom {:count 0})) ; base db
(def *increased
(rum/derived-atom [*db]
::increased
(fn [db]
(inc (:count db)))))
(def *as-map
(rum/derived-atom [*db *increased]
::as-map
(fn [db incd]
{:db db :increased incd})))compared with the way this could be described using derivatives:
(def *db (atom {:count 0}))
(def spec
;; {name [depends-upon derive-fn]}
{:db [[] *db]
:increased [[:db] (fn [db] (inc (:count db)))]
:as-map [[:db :increased] (fn [db incd] {:db db :increased inch})]})The benefit here is that we don't use vars to make sure the dependencies are met and that we provide this information in a way that can easily be turned into a dependency graph which will later help us only calculating required derivatives (done by derivatives-manager). In comparison the first snippet will create derived-atoms and recalculate them whenever any of their dependencies change, no matter if you're using the derived-atom in any of your views.
Re-Frame Subscriptions
- In Re-Frame you can do
(subscribe [:sub-id "a parameter"]), with derivatives you can't. Instead these parameters need to be put intodband be used (potentially via another derivative) from there. - In Re-Frame subscriptions may have side-effects to listen to remote changes etc. This library does not intend to solve this kind of problem and thus side effects are discouraged.