re-posh

re-posh is a ClojureScript library that empowers you to improve your re-frame single-page applications to have a robust and flexible in-page database to manage your application's state.

You can also leverage DatSync to have that in-browser app sync to a server running Datomic or DataScript to simply store your data, or for realtime collaboration between multiple clients.

re-frame is a reactive programming library for writing single-page apps in ClojureScript using Reagent, which wraps Facebook's popular React library for building component-oriented user interfaces.

Posh improves Reagent to allow the declarative binding of user interface components to a local DataScript database. Like Datomic, DataScript supports the powerful q and pull query API's, and Datalog in general.

re-posh allows Posh and re-frame to work together by adding support for re-frame specific subscriptions, events, effects, and co-effects to Posh.

Why?

State management within any application, if treated as a secondary concern, can become a creeping problem that becomes a source of difficult-to-debug problems as the app grows in complexity. re-frame offers a solution to that problem by having a single app-db data structure in the form of a reagent/atom as a single source of truth in the app. UI elements subscribe to changes to that structure and create events that mutate that structure.

re-posh replaces that single atom with a full-featured in-memory database. Now, your application's state has sophisticated data management and querying capabilities that defy complexity. UI elements can bind to the db with all of the expressiveness of Datalog, and the app maintains a single source of truth with an actual database.

Usage

Start a re-frame project and include this dependency:

[re-posh "0.1.4"]

Require re-posh in your app:

(ns example
  (:require [reagent.core :as r]
            [re-posh.core :refer [connect! reg-query-sub reg-pull-sub reg-event-ds]]
            [datascript.core :as d]))

Connection

Connect your DataScript database to re-posh:

(ns example.db
  (:require
    [datascript.core    :as d]
    [re-posh.core       :refer [connect!]]))

(def conn (d/create-conn))
(connect! conn)

Subscriptions

You can subscribe to the DataScript database with a query subscription or with a pull subscription.

Query subscription

You can use reg-query-sub function for subscribe to any query

(reg-query-sub
  :task-ids
  '[ :find  [?tid ...]
     :where [?tid :task/title]])

This function takes two params, subscription name and datalog query. You can use this subscription as regular re-frame subscription

(defn page []
  (let [task-ids (subscribe [:task-ids])]
    (fn []
       ...

Every parameter in a signal will be pass as param to the query

(reg-query-sub
   :task-ids
   '[ :find  [?tid ...]
      :in $ ?param-1 ?param-2
      :where ...

(let [task-ids (subscribe [:task-ids param-1 param-2])]
   ...)

Pull subscription

Pull subscriptions creates subscription to the entity. reg-pull-sub function create pull subscription and takes two params, subscription name and pull pattern. For more details see Datomic Pull

(reg-pull-sub
   :sub-name
   '[*])

 ;; Usage

 (let [entity-id 123
       entity    (subscribe [:sub-name entity-id])])

Events

re-posh uses totally the same solution as re-frame reg-event-db but with datascript database instead. Function reg-event-ds takes event name and event handler. First param for handler is a dereferenced DataScript database. You can do with it whatewer you like, make query or take entities with pull. The second parameter is a signal. Event handler have to return transaction.

(reg-event-ds
 :update-task
 (fn [ds [_ id path value]] ;; ds is not used here, just an example
   [[:db/add id path value]]))

Effects and Co-effects

re-posh introduce one effect and one co-effect. You can use them as regular re-frame effects and co-effects (in fact they are regular re-frame effects and coeffects)

Transact effect

This effect commit transaction into the DataScript database

(ns example.events
   (:require [re-frame.core :as r]))

(r/reg-event-fx
   :my-event
   (fn [cofx [_ id k v]]
      {:transact [[:db/add id k v]]})) ;; return datascript transaction

DS co-effect

This co-effect provide DataScript database into your event handler

(ns example.events
   (:require [re-frame.core :as r]))

(r/reg-event-fx
   :my-event
   [(r/inject-cofx :ds)] ;; inject coeffect
   (fn [{:keys [ds]} [_ id k v]] ;; ds here is the DataScript database
      {:transact [[:db/add id k v]]}))

Contribution

Pull requests are welcome. Email me on denis.takeda@gmail.com if you have any questions, suggestions or proposals.

License

Distributed under the MIT License

frericksm/re-posh