 ;; If you are writing an extension to re-frame, like perhaps
 ;; an effects handler, you may want to use re-frame logging.
 ;;
-;; usage:  (console :error "this is bad: " a-variable " and " anotherv)
-;;         (console :warn "possible breach of containment wall at: " dt)
+;; usage: (console :error "Oh, dear God, it happened: " a-var " and " another)
+;;        (console :warn "Possible breach of containment wall at: " dt)
 (def console loggers/console)
 
 


;; -- effects -----------------------------------------------------------------
(def reg-fx      fx/register)
(def clear-fx    (partial registrar/clear-handlers fx/kind))

;; -- coeffects ---------------------------------------------------------------
(def reg-cofx    cofx/register)
(def inject-cofx cofx/inject-cofx)
(def clear-cofx (partial registrar/clear-handlers cofx/kind))


;; --  Events -----------------------------------------------------------------
(def clear-event (partial registrar/clear-handlers events/kind))

(defn reg-event-db
  "Register the given `id`, typically a namespaced keyword, with the combination of
  `db-handler` and an interceptor chain.
  `db-handler` is a function: (db event) -> db
  `interceptors` is a collection of interceptors, possibly nested (needs flattening).
  `db-handler` is wrapped in an interceptor and added to the end of the chain, so
   that, in the end, there is only a chain.
   The necessary effects and coeffects handler are added to the front of the
   interceptor chain.  These interceptors ensure that app-db is available and updated."
  ([id db-handler]
    (reg-event-db id nil db-handler))
  ([id interceptors db-handler]
   (events/register id [cofx/inject-db fx/do-fx interceptors (db-handler->interceptor db-handler)])))


(defn reg-event-fx
  ([id fx-handler]
   (reg-event-fx id nil fx-handler))
  ([id interceptors fx-handler]
   (events/register id [cofx/inject-db fx/do-fx interceptors (fx-handler->interceptor fx-handler)])))


(defn reg-event-ctx
  ([id handler]
   (reg-event-ctx id nil handler))
  ([id interceptors handler]
   (events/register id [cofx/inject-db fx/do-fx interceptors (ctx-handler->interceptor handler)])))


;; -- interceptors ------------------------------------------------------------

;; Standard interceptors. Detailed docs in std-interceptors.cljs
(def debug       std-interceptors/debug)
(def path        std-interceptors/path)
(def enrich      std-interceptors/enrich)

    [clojure.set               :as set]))


;; This namespace defines the re-frame API

;; When originally writing this re-frame API namespace, we used
;; this technique:
;;    (def api-name (deeper.namespace/where-the-defn-is))
;;
;; Turns out this technique makes it hard:
;;   - to auto-generate API docs
;;   - for IDEs to provide code completion on functions in the API.
;;
;; Which is annoying. But there are pros and cons and we haven't yet
;; revisited the decision. So, sorry, in advance. To compensate we've
;; added more nudity to the official docs.


;; --  dispatch ---------------------------------------------------------------
(def dispatch       router/dispatch)
(def dispatch-sync  router/dispatch-sync)


;; --  subscriptions ----------------------------------------------------------
(def reg-sub        subs/reg-sub)
(def subscribe      subs/subscribe)

(def clear-sub (partial registrar/clear-handlers subs/kind))  ;; think unreg-sub
(def clear-subscription-cache! subs/clear-subscription-cache!)

(defn reg-sub-raw
