factui

by arachne-framework

arachne-framework / factui

Declarative UI State Management for React

133 Stars 9 Forks Last release: Not found 84 Commits 1 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

FactUI

FactUI is a library for efficiently rendering user interfaces declaratively, based on a tuple-oriented data store.

Rationale

Other ClojureScript/React frameworks have already broken important ground in establishing a pattern for data-driven interfaces: the visible UI is a pure function of data. This is a strong concept which has lead to powerful, simple UI programming idioms.

However, this pattern leaves room for different answers to the following questions:

  1. What is the structure of the "application data" that ultimately drives the UI?
  2. What is the pattern for making updates to the application data?

Each library answers these questions in its own way.

FactUI gives its own answers, answers which resolve a number of particularly difficult issues that often end up being pain points (especially in larger applications.)

In broad strokes:

  1. Application state is stored in a single immutable value, in an atom.
  2. Components register queries against the application state.
  3. When the app-state atom is updated, only components with changed query results will re-render.

Query notification on updated facts is provided by the RETE algorithm, which is designed specifically to provide efficient activiation of rules in response to new facts. FactUI uses Clara, an excellent RETE implementation for ClojureScript.

Usage

Note: This section provides documentation using FactUI's integration with the Rum React wrapper. FactUI is not tightly coupled with Rum, it is entirely possible to build integration between FactUI and alternative wrappers (such as Reagent or Om with relatively little effort. However, those have not yet been built.

Initialization

Because queries and rules are built at compile time, FactUI requires a bit of setup.

Step 1: build a rulebase

First, you need to invoke the

factui.api/rulebase
macro at the top level of one of your source files, passing it a rulebase name and any number of namespace names. You must call
rulebase
after you
:require
the namespaces it mentions. Clara will search each of the specified namespaces for query and rule definitions and compile them into a rulebase at macro-expansion time, binding it to a var with the specified name.
(ns example.core
  (:require [factui.api :as f :include-macros true]
            [example.ns-with-rules]
            [example.other-ns-with-rules]))

(f/rulebase my-rulebase example.ns-with-rules example-other-ns-with-rules)

Step 2: define some schema

FactUI requires that you define schema for all the attributes you want to insert. Although adherance to the schema is not rigorously validated (for performance reasons), some attributes are important to ensure correct update semantics, particularly

:db/cardinality
,
:db.type/ref
:db/isComponent
and
:db/unique
.

Schema txdata is structured the same way as it is in Datomic. For example:

(def schema
  [{:db/ident :tasklist/title
    :db/valueType :db.type/string
    :db/cardinality :db.cardinality/one}
   {:db/ident :tasklist/tasks
    :db/valueType :db.type/ref
    :db/cardinality :db.cardinality/many
    :db/isComponent true}

{:db/ident :task/title
 :db/valueType :db.type/string
 :db/cardinality :db.cardinality/one}
{:db/ident :task/completed
 :db/valueType :db.type/boolean
 :db/cardinality :db.cardinality/one}])

Step 3: Define a component

Using the Rum wrapper, components are defined the same way as they always are in Rum. FactUI is introduced by calling the

factui.rum/q
mixin.
q
is a macro that defines a Clara query, and also resolves to a Rum mixin that subscribes to the defined query and causes the component to be re-rendered whenever the query results change.
(ns example.ns-with-rules
  (:require [rum.core :as rum]
            [factui.api :as f :include-macros true]
            [factui.rum :as fr :refer [*results*] :include-macros true]))


(rum/defc TaskList < rum/static (fr/q [:find ?list-title ?task-title :in ?task-list :where [?task-list :tasklist/title ?list-title] [?task-list :tasklist/tasks ?task] [?task :task/title ?task-title]) [app-state ?task-list] (let [list-title (ffirst results) task-titles (map second results)] [:div [:h1 list-title] [:ul (for [title task-titles] [:li.task {:key title} title])]]))

There are several elements here to unpack.

  • The
    rum/static
    mixin is also used. You may use any other mixins in combination with the FactUI mixin, and using
    rum/static
    is reccomended to prevent the component from re-rendering when neither its arguments nor underlying query change.
  • The body of the
    q
    macro is a Datomic-style query, which is compiled and defined as a Clara query.
  • the
    [app-state ?task-list]
    vector defines the arguments to the component. Components with the FactUI mixin have special requirements about the arguments they are passed:
    • The first argument must be an atom containing the application state.
    • The next N arguments are passed as inputs to the query (those defined for the query's
      :in
      clause), where N is the number of arguments specified (this may be zero for queries with no
      :in
      clause).
    • Any additional arguments after the N query inputs are passed on the Rum component as usual and are not processed by the FactUI mixin.
    • By convention, arguments that map to query inputs use a symbol with a leading
      ?
      to visually disambiguate them. This is not required.
  • The
    factui.rum/*results*
    dynamic variable is bound within a component's body. It contains Datomic-style query results, in this case a set of
    [list-title task-title]
    tuples.
  • The remainder of the body is used as the implementation for the React component's
    render
    lifecycle method and should return a single component or Virtual DOM node, as usual (or a Hiccup data structure representing a DOM node, as per Rum.)

Step 3: initialize rendering

Now you can initialize rendering of your application. FactUI's rum wrapper provides a single function to initialize an app state atom. The wrapper also handles ensuring that the application can successfully reload (preserving application state) after a recompile during development (such as from Figwheel.)

factui.rum/initialize
takes 3 arguments:
  1. A var identifying the rulebase to use.
  2. The schema to use.
  3. A function which will be called with an atom containg the application state session on initial load, and whenever the page reloads.

The return value is an atom containing an initialized but empty application state value.

factui.rum/initialize
is usually invoked from within your application's
main
function, like so:
(defn ^:export main
  []
  (let [dom-root (.getElementById js/document "root")
        mount (fn [app-state] (rum/mount ((deref '#RootComponent) app-state)
                                          dom-root))
        app-state (fr/initialize #'rulebase schema mount)]
    (fr/transact! initial-data)))

Note again that the argument for the rulebase must be a var, not a value. This ensures that it can be reloaded after being redefined by hiccup. The user-supplied

mount
function in this example dereferences a var for the same reason; so the new value will get picked up after a Figwheel page reload.

If you are using Figwheel, you should also set the

factui.rum/refresh
function as the value of Figwheel's
:on-jsload
config key to ensure that your application refreshes correctly after a Figwheel reload.

Step 4: transacting some data

You will have noticed the use of

factui.rum/transact!
in the above example.
transact!
is a tiny wrapper around FactUI's core API, which calls
swap!
on the application state atom, transacting the specified txdata and returning a map of tempid bindings that were resolved in the transaction.

An example value for

initial-data
might be:
(def initial-data
  [{:db/id -42
    :tasklist/title "My Tasks"
    :tasklist/tasks [{:task/title "Write a readme"
                      :task/completed true}
                     {:task/title "Write an example"
                      :task/completed false}]}])

Calling

transact!
with this value would update the app-state atom and return
{-42 }
(or whatever the new entity ID is.)

Some applications will call

transact!
directly in event handlers in components. Others may wish to pass around a channel, use a global pub-sub system, or some other intermediary mechanism to give the system a chance to track or modify changes before they are transacted.

That's the basics! The tools described above are enough to get you started writing declarative UIs with FactUI.

Other Features

Standalone queries

You can define named queries separately from a component using the

factui.api/defquery
macro. They have the same syntax as queries defined in
factui.rum/q
:
(f/defquery tasks-for-list
    "Find the IDs of all tasks in the given task list"
    [:find [?task ...]
     :in ?tasklist
     :where
     [?tasklist :tasklist/tasks ?task]])

You can then get the results of the query using the

factui.api/query
function, passing it a session (not the application stat atom itself, but the value which is the contents of that atom), the query name, and any arguments:
(f/query @app-state tasks-for-list 10042)
;; => #{10049 100029 100037#}

Note that queries performed in this manner are not reactive: they simply retrieve results, and do not set up any kind of notification or re-render process.

Standalone rules

You can also define standalone rules to perform logic whenever facts are inserted that cause a particular condition to become true using the

factui.api/defrule
macro.
(f/defrule clean-brushes-rule
  "Add a task to clean the brushes after we finish a painting task"
  [?task :task/title "Paint"]
  [?task :task/complete true]
  [?tasklist :tasklist/tasks ?task]
  =>
  (f/transact! [{:db/id ?tasklist
                 :tasklist/tasks {:task/tittle "Clean Brushes"}}]))

When this rule is part of a rulebase, whenever facts are added which cause the conditions (or "left hand side") of the rule to become true, the consequence (or "right hand side") of the rule will be fired and new data will be added to session as part of the same transaction. The bindings established in the LHS of the rule are available in the RHS, with the same bindings.

Note that

factui.api/transact!
function is not the same as
factui.rum/transact!
. Wheras the version in the Rum API is a simple wrapper around an atom swap, the
transact!
in
factui.api
is a special function that may only be called in the right hand side of a rule, and adds new facts to the current pass over the rules.

Any new facts inserted will have the rules engine run on them as well, until no more new rules are activated. Rules may be recursive, adding facts which cause the same rule to fire again. Try not to write rules which never terminate, and be aware that recursive rules can be bad for performance.

Rules are guaranteed to fire only once for each unique set of bindings, meaning that it is safe to put side effects in the consequence of a rule.

In addition to

factui.api/transact!
, you can also use
factui.api/transact-logical!
to insert facts that will be automatically retracted if the condition for a rule ever becomes untrue. This feature is called "truth maintenance", please read Clara's documentation for a discussion of how it works and some of its limitations.

Transient facts

When defining your schema, you can declare individual attributes to be transient using the

:factui/isTransient
schema attribute.
{:db/ident :task/select
 :db/valueType :db.type/boolean
 :db/cardinality :db.cardinality/one
 :factui/isTransient true}

Transient facts are never persisted in the session: they are removed at the end of every transaction. However, they are active during the rule activation phase, and can be used to perform conditional logic and (optionally) insert more long-lived facts.

Transient facts are often used to create reactions to temporary UI states, such as user clicks or hovers. Using transient facts, you can encode almost all of your application's interaction logic as declarative rules, if you so wish.

Reactive queries

If you want to create a "listener" that will be notified when ever a query's results change, you can do so directly using the

factui.api/register
and
factui.api/deregister
functions. These are what the Rum mixin uses under the hood to provide reactivity to its components.

The

factui.api/register
function takes a session, a query, an argument vector and a channel. It returns a new session, with a listener present, such that whenever a transaction causes the results of the query to change for the provided arguments, the new query results will be placed upon the provided channel.

For example, this code creates a listener on your primary app state atom, for the

tasks-for-list
rule defined above.
(let [results-ch (chan)]
    (swap! app-state f/register  tasks-for-list [42] results-ch)
    (go-loop []
        (when-let [results (

A registration can be removed using

factui.api/deregister
, which takes the same arguments and returns a new session, with the specified channel removed.

Credits

Many thanks to Precept for being the immediate inspiration for this approach. Although I've been thinking about database-driven and rule-driven UIs for some time, Precept pulled a lot of things into focus and crystallized the kind of API I really wanted to see, which FactUI represents.

Also thanks to Ryan Brush and the rest of the Clara team for building an excellent, well-maintained rules engine. FactUI would not be possible without it.

F.A.Q.

Q. OMG it's full of macros. Why...!?

A. That's why it's fast. The ClojureScript version of Clara uses macros to build its RETE network at compile-time, so anything that defines Clara queries needs to use macros as well.

Q. Will I run into performance issues?

A. Maybe. It depends on what rules you write, and how complex the queries for your components are. FactUI easily supports tens of thousands of facts and thousands of simple rules and components. But it's certainly possible to write just a few complex rules, or rules that interact in unexpected ways, which will cause your performance to tank.

Q. The library seems a little bit memory-hungry...

A. Yup, it sure is. The RETE algorithm fundamentally works by trading of memory usage to increase speed. Know your limits, do some benchmarks.

Q. Can I dynamically generate rules!?!!

A. No. Calm yourself and embrace the fact that UI applications have to stop being abstract at some point.

Future Improvments

Datomic Functionality

Many useful features that Datomic provides are not currently supported. We will add support for these over time:

  • Pull Expressions (both reactive and non-reactive)
  • Aggregates in queries
  • Predicates in queries
  • "Transactor" functions

Basic Implementation

Currently, FactUI works by putting a thin wrapper around Clara's external interfaces, enforcing Datom-style semantics (tempids, identity, upsert, cardinality-one) at the boundary. This works fine, but is a tiny bit hacky, as well as causing potential issues in a multi-threaded environment (i.e, not the browser.)

The "correct" way to do it is to implment new types to satisfy Clara's various Memory-related protocols. In theory, this would be both faster and safer. But it's also a lot of work, and a lot of work to get right since it integrates deeply with the internal engine.

The wrapper will do for now, but eventually it would be cool to do it the right way and see what performance looks like.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.