Refn Clojurescript library to mutate and manage resultsets in the re-frame appdb + Re-frame syntactic Sugar Sprinkles

It is at times convenient to have a snapshot of the remote database for CRUD operations in the re-frame appdb. Typically, we end up having a huge catalog of events, effects and subscriptions for various entities and the CRUD operations associated with it. Having a common sub tree, with a top-level resultset key (say :resultset), avoids the need to write explicit subscriptions that could otherwise get very tedious and repetitive.

Refn library provides an utility function called refn that can be used as callback function for various CRUD ops. refn manages the state of the :resultset value in the appdb: adds to it on create, deletes from it when deleting from remote db, handles list pagination and so forth. refn returns a partial that takes a collection as param.

Re-Frame Syntactic Sugar

Not coupled to the refn functions, this library adds some nice syntactic sugar for your regular operations with re-frame events and subs.

Generate docs

Run

make codox

This will generate Codox documentation of the code in api-docs

Deps and Requires

Add following to deps.edn or your cljs deps file

{:deps {omnyway-labs/refn
        {:git/url "https://github.com/omnyway-labs/refn.git"
         :sha "c0653d31fc55b3ae6638887647b12b2576465e36"}}}

(ns myapp.core
  (:require [refn.core :as refn]))

Refn: Working with resultsets

(refn operation entity data)

Here operation is any of :create, :update, :delete or :list. entity is any keyword representing the database table or key to subscribe to.

(ns myapp.events
  (:require
   [re-frame.core :as rf]
   [refn.core :refer [refn defx]]))

(rf/reg-fx ::create-foo
  (fn [param]
    (create-db-entity :foo
                      param
                      (refn :create :foo))))

(refn :create :foo) returns a fn that can be used as a callback-fn typically in most cljs db queries or REST api requests.

And now we can just subscribe to the entity in the resultset

(rf/dispatch ::events/create-foo param)
(rf/subscribe [:resultset entity])
;; e.g
(rf/subscribe [:resultset :foo])

:list operation appends to the resultset collection in the appdb

(rf/reg-fx ::list-foo
  (fn [param]
    (list-db-entity :foo (refn :list :foo))))

:delete removes it from the local appdb. By default, it uses the :id key in the record to dissoc from the list in the appdb.

(rf/reg-fx ::delete-foo
  (fn [param]
    (delete-db-entity :foo (refn :delete :foo))))

Re-Frame Syntactic Sugar

Refn library also provides syntactic wrappers for defining, subscribing re-frame events.

Defining re-frame Events

(ns myppp.events
 (:require [refn.core :refer [defx >> <<]]))

(defx ::foo (fn [param] (do-something param)))

;; and elsewhere
(ns myapp.views
  (:require [myapp.events :as events]
            [refn.core :refer [>>]]))

(>> [::events/foo some-value])

defx is meant for side-effecting events, typically done using reg-fx without needing an intermediate reg-event-fx to dispatch to it. It’s main purpose is to reduce boilerplate code and provide a quick way to trace through events or effects.

>> and << are shortforms for rf/dispatch and rf/subscribe

Defining Subscriptions

(ns myppp.subs
 (:require [refn.core :refer [defsub]]))

(defsub :baz
  (fn [db param]
    (do-something param)))

;; and elsewhere
(ns myapp.views
  (:require [myapp.subs :as subs]
            [refn.core :refer [<<]]))

(<< [:baz some-value])

defsub also has a syntactic shortform to subscribe to top-level keys in the appdb

(defsub :foo)

;; is equivalent to
(rf/reg-sub
 :foo
 (fn [db _]
   (:foo db)))

defub Can also simplify subs that require a keypath to access the app-db

(defsub :foo [:bar :baz])

;; is equivalent to
(rf/reg-sub
 :foo
 (fn [db _]
   (get-in db [:bar :baz)))

Other sweet syntactic options

See the Codox or the code for the descriptions of

• assoc-db
• assoc-in-db
• conj-in
• default
• dissoc-in
• init!

License - Apache 2.0

Copyright 2020-21 Omnyway Inc.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.