Change to Interceptors (away from middleware). This is a big code drop.

Tests pass and todomvc works.
But there is some ugliness to now resolve, and a couple of  unresolved issues.

Author: mike-thompson-day8

CHANGES.md

@@ -2,9 +2,10 @@
 ## 0.8.0  (2016.07.XX)
 
 Staying on the leading edge of new buzzwords is obviously critical for any framework. 
-Angular's terrifying faceplant is a sobering  reminder to us all. 
+Angular's terrifying faceplant is a sobering reminder to us all. 
 With this release, re-frame's already impressive buzzword muscles
-bulge further with new walnuts like "effects", "coeffects", and "de-duplicated signal graph".  I know, right?
+bulge further with new walnuts like "effects", "coeffects", "interceptors"
+and "de-duplicated signal graph".  I know, right?
 
 Some may even find these new features useful.
 
@@ -51,26 +52,26 @@ Joking aside, this is a substantial release which will change how you use re-fra
       2. https://github.com/Day8/re-frame-forward-events-fx
       3. https://github.com/Day8/re-frame-async-flow-fx
 
-  - You can now run and debug re-frame tests on the JVM.  This will be a really big deal for some. 
+  - You can now run and debug re-frame tests on the JVM.  This will be a really big deal for some.
 
     Just to be clear: this does not mean you can run re-frame apps on the JVM (there's no React or 
     Reagent available). But you can debug your handler tests using full JVM tooling goodness.
 
     @samroberton and and @escherize have provided the thought leadership and drive here.  They converted 
     re-frame to `.cljc`, supplying plugable interop for both the `js` and `jvm` platforms.
 
-    They then worked with @danielcompton to create a library of testing utilities which are actually 
-    a nice step forward for both platforms: <br>
+    Further, they have worked with @danielcompton to create a library of testing utilities which are actually 
+    a really nice step forward for both platforms: <br>
     https://github.com/Day8/re-frame-undo
 
-  - the undo/redo feature buried in re-frame has been factored out into its own library.
+  - the undo/redo features buried in re-frame has been factored out into [their own library](https://github.com/Day8/re-frame-undo).
 
-    undo and redo have been a part of re-frame from the beginning, but this feature has been hidden 
-    (not a part of the official API) and not documented. So it nice to see it made available, and fully 
-    documented here: https://github.com/Day8/re-frame-undo
+    undo and redo have been a part of re-frame from the beginning, but they have  
+    not been a part of the official API, and have not been documented. So it nice to see it available, and fully 
+    documented. 
 
-    This library also has [a couple of enhancements](https://github.com/Day8/re-frame-undo#harvesting-and-re-instating)
-    over that which previously existed previously, including a feature which works in with the new effects handler. 
+    This new library also has [a couple of enhancements](https://github.com/Day8/re-frame-undo#harvesting-and-re-instating)
+    over that which previously existed, including a feature which works in with the new effects handler. 
 
   - we now have a logo designed by Sketch Maester @martinklepsch. Thank you Martin!  But remember, no 
     good deed ever goes unpunished - we'll be pestering you every time from now on :-)
@@ -114,7 +115,7 @@ Joking aside, this is a substantial release which will change how you use re-fra
 
   - Bug fix: `post-event-callbacks` were not called when `dispatch-sync` was called.
   - added new API `re-frame.core/clear-post-event-callback` which de-registers a callback 
-    added by `re-frame.core/add-post-event-callback`
+    previously added by `re-frame.core/add-post-event-callback`
   - when an event-handler makes no change to `app-db`, the `debug` middleware now logs a
     single line saying so, rather than a "group".  Makes it slightly easier to grok
     the absence of change.

examples/simple/src/simpleexample/core.cljs

@@ -1,7 +1,7 @@
 (ns simpleexample.core
   (:require-macros [reagent.ratom :refer [reaction]])
   (:require [reagent.core :as reagent]
-            [re-frame.core :refer [reg-event
+            [re-frame.core :refer [reg-event-db
                                    path
                                    reg-sub
                                    dispatch
@@ -20,22 +20,22 @@
 ;; -- Event Handlers ----------------------------------------------------------
 
 
-(reg-event                 ;; setup initial state
+(reg-event-db                 ;; setup initial state
   :initialize                     ;; usage:  (dispatch [:initialize])
   (fn
     [db _]
     (merge db initial-state)))    ;; what it returns becomes the new state
 
 
-(reg-event
+(reg-event-db
   :time-color                     ;; usage:  (dispatch [:time-color 34562])
   (path [:time-color])            ;; this is middleware
   (fn
     [time-color [_ value]]        ;; path middleware adjusts the first parameter
     value))
 
 
-(reg-event
+(reg-event-db
   :timer
   (fn
     ;; the first item in the second argument is :timer the second is the

examples/todomvc/src/todomvc/db.cljs

@@ -54,15 +54,15 @@
 
 (def lsk "todos-reframe")     ;; localstore key
 
-(defn ls->todos
+(defn localstore->todos
   "Read in todos from LS, and process into a map we can merge into app-db."
   []
   (some->> (.getItem js/localStorage lsk)
            (cljs.reader/read-string)   ;; stored as an EDN map.
            (into (sorted-map))         ;; map -> sorted-map
            (hash-map :todos)))         ;; access via the :todos key
 
-(defn todos->ls!
+(defn todos->local-store
   "Puts todos into localStorage"
   [todos]
   (.setItem js/localStorage lsk (str todos)))   ;; sorted-map writen as an EDN map

examples/todomvc/src/todomvc/events.cljs

@@ -1,38 +1,38 @@
 (ns todomvc.events
   (:require
-    [todomvc.db    :refer [default-value ls->todos todos->ls!]]
-    [re-frame.core :refer [reg-event path trim-v after debug]]
+    [todomvc.db    :refer [default-value localstore->todos todos->local-store]]
+    [re-frame.core :refer [reg-event-db path trim-v after debug]]
     [cljs.spec     :as s]))
 
 
-;; -- Middleware --------------------------------------------------------------
-;;
-;; See https://github.com/Day8/re-frame/wiki/Using-Handler-Middleware
+;; -- Interceptors --------------------------------------------------------------
 ;;
+;; XXX Add URL for docs here
+;; XXX Ask Stu to figure out first time spec error
 
 (defn check-and-throw
   "throw an exception if db doesn't match the spec."
   [a-spec db]
-  (if-not (s/valid? a-spec db)
+  (when-not (s/valid? a-spec db)
     (throw (ex-info "spec check failed: " {:problems
                                              (s/explain-str a-spec db)}))))
 
 ;; Event handlers change state, that's their job. But what happens if there's
-;; a bug and it corrupts this state in some subtle way? This middleware is run after
+;; a bug which corrupts app state in some subtle way? This interceptor is run after
 ;; each event handler has finished, and it checks app-db against a spec.  This
 ;; helps us detect event handler bugs early.
-(def check-spec-mw (after (partial check-and-throw :todomvc.db/db)))
+(def check-spec-interceptor (after (partial check-and-throw :todomvc.db/db)))
 
 
-(def ->ls (after todos->ls!))    ;; middleware to store todos into local storage
+(def ->local-store (after todos->local-store))    ;; interceptor to store todos into local storage
 
 
-;; middleware for any handler that manipulates todos
-(def todo-middleware [check-spec-mw   ;; ensure the spec is still valid
-                      (path :todos)   ;; 1st param to handler will be the value from this path
-                      ->ls            ;; write to localstore each time
-                      (when ^boolean js/goog.DEBUG debug)       ;; look in your browser console
-                      trim-v])        ;; remove the first (event id) element from the event vec
+;; interceptors for any handler that manipulates todos
+(def todo-interceptors [check-spec-interceptor   ;; ensure the spec is still valid
+                        (path :todos)   ;; 1st param to handler will be the value from this path
+                        ->local-store                          ;; write to localstore each time
+                        (when ^boolean js/goog.DEBUG debug)    ;; look in your browser console
+                        trim-v])                               ;; removes first (event id) element from the event vec
 
 
 ;; -- Helpers -----------------------------------------------------------------
@@ -47,71 +47,73 @@
 
 ;; -- Event Handlers ----------------------------------------------------------
 
+;; XXX make localstore a coeffect interceptor
+
                                   ;; usage:  (dispatch [:initialise-db])
-(reg-event                        ;; On app startup, create initial state
+(reg-event-db                     ;; on app startup, create initial state
   :initialise-db                  ;; event id being handled
-  check-spec-mw                   ;; afterwards: check that app-db matches the spec
+  check-spec-interceptor          ;; after the event handler runs, check that app-db matches the spec
   (fn [_ _]                       ;; the handler being registered
-    (merge default-value (ls->todos))))  ;; all hail the new state
+    (merge default-value (localstore->todos))))  ;; all hail the new state
 
 
                                   ;; usage:  (dispatch [:set-showing  :active])
-(reg-event                        ;; this handler changes the todo filter
+(reg-event-db                     ;; this handler changes the todo filter
   :set-showing                    ;; event-id
-  [check-spec-mw (path :showing) trim-v]  ;; middleware  (wraps the handler)
+  [check-spec-interceptor (path :showing) trim-v]    ;; this colelction of interceptors wrap wrap the handler
 
-  ;; Because of the path middleware above, the 1st parameter to
+  ;; Because of the path interceptor above, the 1st parameter to
   ;; the handler below won't be the entire 'db', and instead will
   ;; be the value at a certain path within db, namely :showing.
-  ;; Also, the use of the 'trim-v' middleware means we can omit
+  ;; Also, the use of the 'trim-v' interceptor means we can omit
   ;; the leading underscore from the 2nd parameter (event vector).
-  (fn [old-kw [new-filter-kw]]    ;; handler
-    new-filter-kw))               ;; return new state for the path
+  (fn [old-keyword [new-filter-kw]]  ;; handler
+    new-filter-kw))                  ;; return new state for the path
 
 
                                   ;; usage:  (dispatch [:add-todo  "Finsih comments"])
-(reg-event                        ;; given the text, create a new todo
+(reg-event-db                     ;; given the text, create a new todo
   :add-todo
-  todo-middleware
-  (fn [todos [text]]              ;; "path" middlware in "todo-middleware" means 1st parameter is :todos
+  todo-interceptors
+  (fn [todos [text]]              ;; the "path" interceptor in `todo-interceptors` means 1st parameter is :todos
     (let [id (allocate-next-id todos)]
       (assoc todos id {:id id :title text :done false}))))
 
 
-(reg-event
+(reg-event-db
   :toggle-done
-  todo-middleware
+  todo-interceptors
   (fn [todos [id]]
     (update-in todos [id :done] not)))
 
 
-(reg-event
+(reg-event-db
   :save
-  todo-middleware
+  todo-interceptors
   (fn [todos [id title]]
     (assoc-in todos [id :title] title)))
 
 
-(reg-event
+(reg-event-db
   :delete-todo
-  todo-middleware
+  todo-interceptors
   (fn [todos [id]]
     (dissoc todos id)))
 
 
-(reg-event
+(reg-event-db
   :clear-completed
-  todo-middleware
+  todo-interceptors
   (fn [todos _]
-    (->> (vals todos)                ;; remove all todos where :done is true
+    (->> (vals todos)                ;; find the ids of all todos where :done is true
          (filter :done)
          (map :id)
-         (reduce dissoc todos))))    ;; returns the new version of todos
+         (reduce dissoc todos))))    ;; now do the delete of these done ids
 
 
-(reg-event
+(reg-event-db
   :complete-all-toggle
-  todo-middleware
+  todo-interceptors
   (fn [todos _]
     (let [new-done (not-every? :done (vals todos))]   ;; toggle true or false?
       (reduce #(assoc-in %1 [%2 :done] new-done)

src/re_frame/core.cljc

@@ -5,64 +5,85 @@
     [re-frame.fx         :as fx]
     [re-frame.router     :as router]
     [re-frame.loggers    :as loggers]
-    [re-frame.middleware :as middleware]))
+    [re-frame.registrar  :as registrar]
+    [re-frame.interceptor :as interceptor :refer [base ->interceptor db-handler->interceptor fx-handler->interceptor]]))
 
 
 ;; --  dispatch
 (def dispatch         router/dispatch)
 (def dispatch-sync    router/dispatch-sync)
 
 
+;; XXX move API functions up here
+
 ;; --  subscribe
 (def reg-sub-raw         subs/register)
 (def reg-sub             subs/register-pure)
-(def clear-all-subs!     subs/clear-all-handlers!)
 (def subscribe           subs/subscribe)
 
 ;; --  effects
-(def reg-fx         fx/register)
-(def clear-fx!      fx/clear-handler!)
-(def clear-all-fx!  fx/clear-all-handlers!)
+(def reg-fx       fx/register)
+(def clear-fx     (partial registrar/clear-handlers fx/kind))
 
+;; XXX add a clear all handlers:
+;; XXX add a push handlers for testing purposes
 
 ;; --  middleware
-(def pure        middleware/pure)
-(def fx          fx/fx)
-(def debug       middleware/debug)
-(def path        middleware/path)
-(def enrich      middleware/enrich)
-(def trim-v      middleware/trim-v)
-(def after       middleware/after)
-(def on-changes  middleware/on-changes)
+
+; (def fx          fx/fx)
+(def debug       interceptor/debug)
+(def path        interceptor/path)
+(def enrich      interceptor/enrich)
+(def trim-v      interceptor/trim-v)
+(def after       interceptor/after)
+(def on-changes  interceptor/on-changes)
 
 ;; --  Events
-(def clear-all-events!   events/clear-all-handlers!)
-(def clear-event!        events/clear-handler!)
 
-;; Registers a pure event handler. Places pure middleware in the correct, LHS position.
+;; usage (clear-event! :some-id)
+(def clear-event!  (partial registrar/clear-handlers events/kind))    ;; XXX name with !
 
-(defn reg-event
-  ([id handler]
-    (events/register-base id pure handler))
-  ([id middleware handler]
-    (events/register-base id [pure middleware] handler)))
 
 
-;; Registers an effectful event handler. Places fx middleware in the correct, LHS position.
+;; XXX note name change in changes.md
+
+(defn reg-event-db
+  "Register the given `id`, typically a kewyword, 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 flattenting).
+  `db-handler` is wrapped in an interceptor and added to the end of the chain, so in the end
+   there is only a chain."
+  ([id db-handler]
+    (reg-event-db id nil db-handler))
+
+  ([id interceptors db-handler]
+   (events/register id [base interceptors (db-handler->interceptor db-handler)])))   ;; XXX add a base-interceptor
+
+
 (defn reg-event-fx
+  ([id fx-handler]
+   (reg-event-fx id nil fx-handler))
+
+  ([id interceptors fx-handler]
+   (events/register id [base interceptors (fx-handler->interceptor fx-handler)])))   ;; XXX add a base-interceptor
+
+
+(defn reg-event-context
   ([id handler]
-   (events/register-base id fx handler))
-  ([id middleware handler]
-   (events/register-base id [fx middleware] handler)))
+   (reg-event-context id nil handler))
+
+  ([id interceptors handler]
+   (events/register id [base interceptors handler])))   ;;   XXX can't just put in handler, must wrap it
 
 
 ;; --  Logging -----
 ;; Internally, re-frame uses the logging functions: warn, log, error, group and groupEnd
 ;; By default, these functions map directly to the js/console implementations,
 ;; but you can override with your own fns (set or subset).
 ;; Example Usage:
-;;   (defn my-fn [& args]  (post-it-somewhere (apply str args)))
-;;   (re-frame.core/set-loggers!  {:warn my-fn :log my-fn})    ;; I should override the rest of them too.
+;;   (defn my-fn [& args]  (post-it-somewhere (apply str args)))  ;; here is my alternative
+;;   (re-frame.core/set-loggers!  {:warn my-fn :log my-fn})       ;; override the defaults with mine
 (def set-loggers! loggers/set-loggers!)
 
 ;; If you are writing an extension to re-frame, like perhaps
@@ -76,7 +97,7 @@
 ;; -- Event Procssing Callbacks
 
 (defn add-post-event-callback
-  "Registers a callback function `f` to be called after each event is procecessed
+  "Registers a function `f` to be called after each event is procecessed
    `f` will be called with two arguments:
     - `event`: a vector. The event just processed.
     - `queue`: a PersistentQueue, possibly empty, of events yet to be processed.
@@ -87,11 +108,11 @@
        handlers for the one event, etc.  Hook in here.
      - libraries providing 'isomorphic javascript' rendering on  Nodejs or Nashorn.
 
-  'id' is typically a keyword. It is an identifier, supplied initially
-  at \"add time\", which can be subsequently be used to remove a callback.
+  'id' is typically a keyword. Supplied at \"add time\" so it can subsequently
+  be used at \"remove time\" to get rid of the right callback.
   "
   ([f]
-    (router/add-post-event-callback re-frame.router/event-queue f f))
+   (add-post-event-callback f f))   ;; use f as its own identifier
   ([id f]
    (router/add-post-event-callback re-frame.router/event-queue id f)))
 
@@ -105,8 +126,8 @@
 ;; Assisting the v0.0.7 ->  v0.0.8 tranistion.
 (defn register-handler
   [& args]
-  (console :warn  "re-frame:  \"register-handler\" has been renamed \"reg-event\"")
-  (apply reg-event args))
+  (console :warn  "re-frame:  \"register-handler\" has been renamed \"reg-event-db\"")
+  (apply reg-event-db args))
 
 (defn register-sub
   [& args]

src/re_frame/events.cljc

@@ -1,109 +1,59 @@
 (ns re-frame.events
-  (:require [re-frame.db         :refer [app-db]]
-            [re-frame.utils      :refer [first-in-vector]]
-            [re-frame.loggers    :refer [console]]))
+  (:require [re-frame.db          :refer [app-db]]
+            [re-frame.utils       :refer [first-in-vector]]
+            [re-frame.interop     :refer [empty-queue debug-enabled?]]
+            [re-frame.registrar   :refer [get-handler register-handler]]
+            [re-frame.loggers     :refer [console]]
+            [re-frame.interceptor :as  interceptor]))
 
 
-;; -- composing middleware  -----------------------------------------------------------------------
+(def kind :event)
+(assert (re-frame.registrar/kinds kind))
 
+(defn- flatten-and-remove-nils
+  "`interceptors` might have nested collections, and contain nil elements.
+  return a flat collection, with all nils removed."
+  [id interceptors]
+  (let [make-chain  #(->> % flatten (remove nil?))]
+    (if-not debug-enabled?
+      (make-chain interceptors)
+      (do    ;; do a whole lot of development time checks
+        (when-not (coll? interceptors)
+          (console :error  "re-frame: when registering " id ", expected a collection of interceptors, got: " interceptors))
+        (let [chain (make-chain interceptors)]
+          (when (empty? chain)
+            (console :error  "re-frame: when registering " id ", given an empty interceptor chain"))
+          (when-let [not-i (some (comp not interceptor/interceptor?) chain)]
+            (if (fn? not-i)
+              (console :error  "re-frame: when registering " id ", got a function instead of an interceptor. Did you provide an old style middleware by mistake? Got: " not-i)
+              (console :error  "re-frame: when registering " id ", expected interceptors, but got: " not-i)))
+          chain)))))
 
-(defn report-middleware-factories
-  "See https://github.com/Day8/re-frame/issues/65"
-  [v]
-  (letfn [(name-of-factory
-            [f]
-            (-> f meta :re-frame-factory-name))
-          (factory-names-in
-            [v]
-            (remove nil? (map name-of-factory v)))]
-    (doseq [name (factory-names-in v)]
-      (console :error "re-frame: \"" name "\" is a factory. It must be called like this \"(" name " ...)\", whereas you just used \"" name "\"."))))
 
+(defn register
+  "Associate given `event id` with the given collection of interceptors.
 
-(defn comp-middleware
-  "Use \"comp\" to compose a vector 'v' of middleware.
-  For convienience, if 'v' is a function (assumed to be middleware already), return it unchanged.
-  Prior to the \"comp\", flatten is used to remove all nested vectors, and nils are removed.
-  Filtering out nils allows us to create Middleware conditionally like this:
-     (comp-middleware [pure (when debug? debug)])  ;; that 'when' might leave a nil"
-  [v]
-  (cond
-    (fn? v)    v  ;; assumed to be existing middleware
-    (coll? v)  (let [v (remove nil? (flatten v))]
-                 (report-middleware-factories v)
-                 (apply comp v))
-    :else      (console :warn "re-frame: comp-middleware expects a vector, got: " v)))
+   `interceptors` may have nested collections and may contain nils, so process them
+   into a nice linear collection before registration.
 
+   An `event handler` will likely be at the end of the chain (wrapped in an interceptor)."
+  [id interceptors]
+  (register-handler kind id (flatten-and-remove-nils id interceptors)))
 
-;; -- the register of event handlers --------------------------------------------------------------
 
-(def ^:private id->fn  (atom {}))
 
-
-(defn lookup-handler
-  [event-id]
-  (get @id->fn event-id))
-
-
-(defn clear-all-handlers!
-  []
-  (reset! id->fn {}))
-
-
-(defn clear-handler!
-  [id]
-  (if (lookup-handler id)
-    (swap! id->fn dissoc id)
-    (console :warn "re-frame: unable to clear event handler for  " id ". Not  defined.")))
-
-
-(defn register-base
-  "register a handler for an event.
-  This is low level and it is expected that a higher level function like
-  \"re-frame.core/reg-event\" or  \"re-frame.core/reg-event-fx\" would generally be used."
-  ([event-id handler-fn]
-   (when (contains? @id->fn event-id)
-     (console :warn "re-frame: overwriting an event-handler for: " event-id)) ;; allow it, but warn.
-   (swap! id->fn assoc event-id handler-fn)
-   nil)
-
-  ([event-id middleware handler-fn]
-   (let [mid-ware    (comp-middleware middleware)           ;; compose the middleware
-         midware+hfn (mid-ware handler-fn)]                 ;; wrap the handler in the middleware
-     (register-base event-id midware+hfn))))
-
-
-
-
-;; -- lookup and call -----------------------------------------------------------------------------
+;; -- handle event --------------------------------------------------------------------------------
 
 (def ^:dynamic *handling* nil)    ;; remember what event we are currently handling
 
-
 (defn handle
-  "Given an event vector, look up the handler, then call it.
-  By default, handlers are not assumed to be pure. They are called with
-  two paramters:
-    - the `app-db` atom
-    - the event vector
-  The handler is assumed to side-effect on `app-db` - the return value is ignored.
-  To write a pure handler, use the \"pure\" middleware when registering the handler."
+  "Given an event vector, look up the associated intercepter chain, and execute it."
   [event-v]
-  (let [event-id    (first-in-vector event-v)
-        handler-fn  (lookup-handler event-id)]
-    (if (nil? handler-fn)
-      (console :error "re-frame: no event handler registered for: \"" event-id "\". Ignoring.")
+  (let [event-id  (first-in-vector event-v)]
+    (if-let [interceptors  (get-handler kind event-id true)]
       (if *handling*
-        (console :error "re-frame: while handling \""  *handling*
-                 "\"  dispatch-sync was called for \"" event-v
-                 "\". You can't call dispatch-sync within an event handler.")
+        (console :error "re-frame: while handling \""  *handling* "\"  dispatch-sync was called for \"" event-v "\". You can't call dispatch-sync within an event handler.")
         (binding [*handling*  event-v]
-          (let [stack (some-> event-v
-                              meta
-                              :stack)]
-            (try
-              (handler-fn app-db event-v)
-              (catch #?(:cljs :default :clj Exception) e
-                (console :warn stack) ;; output a msg to help to track down dispatching point
-                (throw e)))))))))
+          (interceptor/execute event-v interceptors))))))
+
 

src/re_frame/fx.cljc

@@ -3,6 +3,7 @@
     [re-frame.router  :as router]
     [re-frame.db      :refer [app-db]]
     [re-frame.events  :as events]
+    [re-frame.registrar  :refer [get-handler clear-handlers register-handler]]
     [re-frame.interop :refer [ratom? set-timeout!]]
     [re-frame.loggers :refer [console]]))
 
@@ -15,105 +16,88 @@
 
 ;; -- Registration ------------------------------------------------------------
 
-(def ^:private id->handler-fn  (atom {}))
-
-(defn lookup-handler
-  [effect-id]
-  (get @id->handler-fn effect-id))
-
-
-(defn clear-all-handlers!
-  []
-  (reset! id->handler-fn {}))
-
-
-(defn clear-handler!
-  [effect-id]
-  (if (lookup-handler effect-id)
-    (swap! id->handler-fn dissoc effect-id)
-    (console :warn "re-frame: unable to clear effect handler for  " effect-id ". Not defined.")))
 
+(def kind :fx)
+(assert (re-frame.registrar/kinds kind))
 
 (defn register
-  "register a handler fn for an effect."
-  [effect-id handler-fn]
-  (when (lookup-handler effect-id)
-    (console :warn "re-frame: overwriting an effects handler for: " effect-id))   ;; allow it, but warn.
-  (swap! id->handler-fn assoc effect-id handler-fn))
+  [id handler-fn]
+  (register-handler kind id handler-fn))
 
 
 ;; -- Standard Builtin Effects Handlers  --------------------------------------
 
-;; Dispatch event(s) after some time.
-;; Example:
-;; {:dispatch-later [{:ms 200 :dispatch [:event-id "param"]}    ;;  in 200ms do this: (dispatch [:event-id "param"])
-;;                   {:ms 100 :dispatch [:also :this :in :100ms]}]}
+
+;; :dispatch-later
+;;
+;; `dispatch` one or more events in given times on the future. Expects a collection
+;; of maps with two keys:  :`ms` and `:dispatch`
+;;
+;; usage:
+;;
+;;    {:dispatch-later [{:ms 200 :dispatch [:event-id "param"]}    ;;  in 200ms do this: (dispatch [:event-id "param"])
+;;                      {:ms 100 :dispatch [:also :this :in :100ms]}]}
 ;;
 (register
   :dispatch-later
   (fn [effects-v]
-    ;TODO: use Spec to verify vector and elements when clj 1.9.0 is rel.
     (doseq  [{:keys [ms dispatch] :as effect} effects-v]
         (if (or (empty? dispatch) (-> ms number? not))
-          (console :warn "re-frame: bad values given to :dispatch-later. Got: " effect ". Ignored.")
+          (console :error "re-frame: ignoring bad :dispatch-later value: " effect)
           (set-timeout! #(router/dispatch dispatch) ms)))))
 
 
-;; Supply a vector. For example:
+;; :dispatch
 ;;
+;; `dispatch` one event. Excepts a single vector.
+;;
+;; usage:
 ;;   {:dispatch [:event-id "param"] }
 
 (register
   :dispatch
   (fn [val]
-    (when-not (vector? val)
-      (console :warn "re-frame: the value for :dispatch is not a vector. Got: " val))
-    (router/dispatch val)))
+    (if-not (vector? val)
+      (console :error "re-frame: ignoring bad :dispatch value. Expected a vector, but got: " val)
+      (router/dispatch val))))
 
 
-;; Supply sequencial coll. For example:
+;; :dispatch-n
+;;
+;; `dispatch` more than one event. Expects a list or vector of events. Something for which
+;; sequential? returns true.
 ;;
+;; usage:
 ;;   {:dispatch-n (list [:do :all] [:three :of] [:these])}
 ;;
-;; Coll can be anything that returns true to sequential? but should not be a map
-;; NOTE: this does not include Set
 (register
   :dispatch-n
   (fn [val]
-    (when-not (sequential? val)
-      (console :warn "re-frame: the value for :dispatch-n is not sequential. Got: " val))
+    (if-not (sequential? val)
+      (console :error "re-frame: ignoring bad :dispatch-n value. Expected a collection, got got: " val))
     (doseq [event val] (router/dispatch event))))
 
 
+;; :deregister-event-handler
+;;
+;; removes an event handler. Expects either a single id (typically a keyword), or a seq of ids.
+;;
+;; usage:
+;;   {:deregister-event-handler: :my-id)}
+;; or:
+;;   {:deregister-event-handler: [:one-id :another-id]}
+;;
 (register
   :deregister-event-handler
   (fn [val]
-    (if (sequential? val)
-      (doall (map events/clear-handler! val))
-      (events/clear-handler! val))))
+    (let [clear-event (partial clear-handlers events/kind)]
+      (if (sequential? val)
+        (doall (map clear-event val))
+        (clear-event val)))))
 
 
 (register
   :db
   (fn [val]
     (reset! app-db val)))
 
-;; -- Middleware --------------------------------------------------------------
-
-
-(defn fx
-  [handler]
-  (fn fx-handler
-    [app-db event-vec]
-    (if-not (ratom? app-db)
-        (if (map? app-db)
-          (console :warn "re-frame: Did you use \"fx\" middleware with \"reg-event\"?  Use \"reg-event-fx\" instead (and don't directly use \"fx\")")
-          (console :warn "re-frame: \"fx\" middleware not given a Ratom.  Got: " app-db)))
-    (let [run-effect (fn [[key val]]
-                       (if-let [effect-fn  (lookup-handler key)]
-                         (effect-fn val)
-                         (console :error "re-frame: no effects handler registered for: " key ". Ignoring")))
-          world   {:db @app-db}]
-      (->> (handler world event-vec)   ;; is expected to return a map of effects
-           (map run-effect)            ;; process the returned effects
-           doall))))

src/re_frame/interceptor.cljc

@@ -0,0 +1,50 @@
+(ns re-frame.registrar
+  (:require  [re-frame.interop :refer [debug-enabled?]]
+             [re-frame.loggers    :refer [console]]))
+
+
+;; kinds of handlers
+(def kinds #{:event :fx :sub})
+
+;; This atom contains a register of all handlers.
+;; Is a map keyed first by kind (of handler), and then id.
+;; leaf nodes are handlers.
+(def ^:private kind->id->handler  (atom {}))
+
+
+(defn get-handler
+
+  ([kind id]
+   (-> (get @kind->id->handler kind)
+       (get id)))
+
+  ([kind id required?]
+   (let [handler (get-handler kind id)]
+     (when debug-enabled?
+       (when (and required? (nil? handler))
+         (console :error "re-frame: no " (str kind) " handler registered for: " id)))
+     handler)))
+
+
+(defn register-handler
+  [kind id handler-fn]
+  (when debug-enabled?
+    (when (get-handler kind id false)
+      (console :warn "re-frame: overwriting " (str kind) " handler for: " id)))   ;; allow it, but warn. Happens on figwheel reloads.
+  (swap! kind->id->handler assoc-in [kind id] handler-fn)
+  handler-fn)    ;; note: returns the just registered handler
+
+
+(defn clear-handlers
+  ([]            ;; clear all kinds
+   (reset! kind->id->handler {}))
+
+  ([kind]        ;; clear all handlers for this kind
+   (assert (kinds kind))
+   (swap! kind->id->handler dissoc kind))
+
+  ([kind id]     ;; clear a single handler for a kind
+   (assert (kinds kind))
+   (if (get-handler kind id)
+     (swap! kind->id->handler update-in [kind] dissoc id)
+     (console :warn "re-frame: can't clear " (str kind) " handler for  " id ".  Not found."))))

src/re_frame/middleware.cljc

@@ -16,18 +16,19 @@
 ;;
 ;; But browsers only have a single thread of control and we must be
 ;; careful to not hog the CPU. When processing events one after another, we
-;; must hand back control to the browser regularly, so it can redraw, process
+;; must regularly hand back control to the browser, so it can redraw, process
 ;; websockets, etc. But not too regularly! If we are in a de-focused browser
 ;; tab, our app will be CPU throttled. Each time we get back control, we have
 ;; to process all queued events, or else something like a bursty websocket
 ;; (producing events) might overwhelm the queue. So there's a balance.
 ;;
 ;; The processing/handling of an event happens "asynchronously" sometime after
 ;; that event was enqueued via "dispatch". The original implementation of this router loop
-;; used core.async. It was fairly simple, and it mostly worked, but it did not
-;; give enough control. So now we hand-roll our own, finite-state-machine and all.
+;; used `core.async`. As a result, it was fairly simple, and it mostly worked,
+;; but it did not give enough control. So now we hand-roll our own,
+;; finite-state-machine and all.
 ;;
-;; The strategy is this:
+;; In what follows, the strategy is this:
 ;;   - maintain a FIFO queue of `dispatched` events.
 ;;   - when a new event arrives, "schedule" processing of this queue using
 ;;     goog.async.nextTick, which means it will happen "very soon".
@@ -38,7 +39,7 @@
 ;;     and do these new events in the next processing cycle. That way we drain
 ;;     the queue up to a point, but we never hog the CPU forever. In
 ;;     particular, we handle the case where handling one event will beget
-;;     another event. The freshly begat event will be handled next cycle,
+;;     another event. The freshly begatted event will be handled next cycle,
 ;;     with yielding in-between.
 ;;   - In some cases, an event should not be handled until after the GUI has been
 ;;     updated, i.e., after the next Reagent animation frame. In such a case,
@@ -48,7 +49,7 @@
 ;;     events are processed sequentially: we handle one event completely
 ;;     before we handle the ones behind it.
 ;;
-;; Implementation Notes:
+;; Implementation notes:
 ;;   - queue processing can be in a number of states: scheduled, running, paused
 ;;     etc. So it is modeled as a Finite State Machine.
 ;;     See "-fsm-trigger" (below) for the states and transitions.
@@ -65,7 +66,7 @@
    :yield     next-tick})               ;; almost immediately
 
 
-;; Abstract representation of the Event Queue
+;; Event Queue Abstraction
 (defprotocol IEventQueue
 
   ;; -- API
@@ -221,9 +222,13 @@
 ;;
 
 (defn dispatch
-  "Queue an event to be processed by the registered handler function.
+  "Queue the given event for processing by the registered event handler.
 
-  Usage example:
+  Just to be clear: the event handler is not run immediately - it is not run
+  synchronously. It will likely be run 'very soon', although it may be
+  added to the end of a FIFO queue which already contain events.
+
+  Usage:
      (dispatch [:delete-item 42])"
   [event-v]
   (let [;; At the point of dispatch, we capture the current stack.
@@ -239,19 +244,20 @@
                   :clj  "n/a")]
     (if (nil? event-v)
       (throw (ex-info "re-frame: you called \"dispatch\" without an event vector." {}))
-      (push event-queue (with-meta event-v {:stack stack}))))
+      #_(push event-queue (with-meta event-v {:stack stack}))
+      (push event-queue event-v)))
   nil)                                           ;; Ensure nil return. See https://github.com/Day8/re-frame/wiki/Beware-Returning-False
 
 
 (defn dispatch-sync
-  "Immediately process an event using the registered handler.
+  "Sychronously (immediaetly!) process the given event using the registered handler.
 
-  Generally, you shouldn't use this. Use \"dispatch\" instead.  It
-  is an error to even try and use it within an event handler.
+  Generally, you shouldn't use this - you should use `dispatch` instead.  It
+  is an error to use `dispatch-sync` within an event handler.
 
-  Usage example:
+  Usage:
      (dispatch-sync [:delete-item 42])"
   [event-v]
   (handle event-v)
-  (-call-post-event-callbacks event-queue event-v)  ;; ugly hack.  Just so post-event-callbacks get called
+  (-call-post-event-callbacks event-queue event-v)  ;; slightly ugly hack. Run the registered post event callbacks.
   nil)                                              ;; Ensure nil return. See https://github.com/Day8/re-frame/wiki/Beware-Returning-False

src/re_frame/registrar.cljc

@@ -3,34 +3,31 @@
    [re-frame.db    :refer [app-db]]
    [re-frame.interop :refer [add-on-dispose! debug-enabled? make-reaction ratom?]]
    [re-frame.loggers :refer [console]]
+   [re-frame.registrar  :refer [get-handler register-handler]]
    [re-frame.utils :refer [first-in-vector]]))
 
 
 ;; -- Subscription Handler Lookup and Registration --------------------------------------------------
-
-;; Maps from a query-id to a handler function.
-(def ^:private qid->fn (atom {}))
+(def kind :sub)
+(assert (re-frame.registrar/kinds kind))
 
 (defn register
-  "Registers a subscription handler function for an query id"
+  "Register a subscription handler fucntion for an query id"
   [query-id handler-fn]
-  (if (contains? @qid->fn query-id)
-    (console :warn "re-frame: overwriting subscription handler for: " query-id))  ;; allow it, but warn. Happens on figwheel reloads.
-  (swap! qid->fn assoc query-id handler-fn))
+  (register-handler kind query-id handler-fn))
 
 
 ;; -- Subscription cache -----------------------------------------------------
 ;;
-;; De-duplicate subscriptions. If two or more identical subscriptions
+;; De-duplicate subscriptions. If two or more equal subscriptions
 ;; are concurrently active, we want only one handler running.
-;; Two subscriptions are "identical" if their query vectors
-;; test "=".
+;; Two subscriptions are "equal" if their query vectors test "=".
 (def ^:private query->reaction (atom {}))
 
 (defn clear-all-handlers!
   "Unregisters all existing subscription handlers"
   []
-  (reset! qid->fn {})
+  ; (reset! qid->fn {})     XXX
   (reset! query->reaction {}))
 
 (defn cache-and-return
@@ -61,7 +58,7 @@
      (do (console :log "Using cached subscription: " query-v)
          cached)
      (let [query-id   (first-in-vector query-v)
-           handler-fn (get @qid->fn query-id)]
+           handler-fn (get-handler kind query-id)]
        (console :log "Subscription created: " query-v)
        (if-not handler-fn
          (console :error "re-frame: no subscription handler registered for: \"" query-id "\". Returning a nil subscription."))
@@ -72,7 +69,7 @@
      (do (console :log "Using cached subscription: " v " and " dynv)
          cached)
      (let [query-id   (first-in-vector v)
-           handler-fn (get @qid->fn query-id)]
+           handler-fn (get-handler kind query-id)]
        (when debug-enabled?
          (when-let [not-reactive (not-empty (remove ratom? dynv))]
            (console :warn "re-frame: your subscription's dynamic parameters that don't implement IReactiveAtom: " not-reactive)))
@@ -87,6 +84,9 @@
 
 ;; -- Helper code for register-pure -------------------
 
+;; add `metric`  which   (metric :using-cached-subscription  {:text
+;; XXX no need for maps
+
 (defn- map-vals
   "Returns a new version of 'm' in which 'f' has been applied to each value.
   (map-vals inc {:a 4, :b 2}) => {:a 5, :b 3}"
@@ -98,7 +98,7 @@
   [data]
   (cond
     (map? data)  (map-vals deref data)
-    (coll? data) (map deref data)
+    (sequential? data) (map deref data)
     :else @data))
 
 (defn register-pure
@@ -113,7 +113,7 @@
   In this example the entire app-db is derefed and passed to the subscription
   function as a singleton
 
-      ```(subs/register-pure
+      ```(register-pure
            :a-b-sub
            (fn [q-vec d-vec]
                [(subs/subscribe [:a-sub])
@@ -126,7 +126,7 @@
   actually). Again the subscriptions are derefed and passed to the subscription
   function
 
-      ```(subs/register-pure
+      ```(register-pure
            :a-b-sub
            :<- [:a-sub]
            :<- [:b-sub]
@@ -135,9 +135,9 @@
   of cases where only a simple subscription is needed without any parameters
 
   "
-  [sub-name & args]
-  (let [f                        (last args)  ;; grab the last arg
-        middle-args              (butlast args)    ;; grab the middle args
+  [sub-id & args]
+  (let [f                        (last args)       ;; computation function
+        middle-args              (butlast args)    ;; middle args may be empty, or one or more :<-,  or a single signal fn
         maybe-func               (first middle-args)
         sub-fn                   (when (fn? maybe-func) maybe-func)
         arrow-args               (if (fn? maybe-func)
@@ -149,7 +149,7 @@
     (cond
       sub-fn                   ;; first case the user provides a custom sub-fn
       (register
-        sub-name
+        sub-id
         (fn subs-handler-fn    ;; multi-arity to match the arities `subscribe` might invoke.
           ([db q-vec]
            (let [subscriptions (sub-fn q-vec)]
@@ -159,9 +159,10 @@
            (let [subscriptions (sub-fn q-vec d-vec)]
              (make-reaction
               (fn [] (f (multi-deref subscriptions) q-vec d-vec)))))))
+
       (seq arrow-args)              ;; the user uses the :<- sugar
       (register
-        sub-name
+        sub-id
         (letfn [(get-subscriptions []
                   (let [subscriptions (map subscribe arrow-subs)]
                     (if (< 1 (count subscriptions))
@@ -176,9 +177,10 @@
             (let [subscriptions (get-subscriptions)]
               (make-reaction
                (fn [] (f (multi-deref subscriptions) q-vec d-vec))))))))
+
       :else
       (register ;; the simple case with no subs
-        sub-name
+        sub-id
         (fn subs-handler-fn
           ([db q-vec]
            (make-reaction (fn [] (f @db q-vec))))

src/re_frame/router.cljc

@@ -10,7 +10,7 @@
   "tests that an error thrown generates an informational warning"
   (re-frame/clear-all-events!)
 
-  (re-frame/reg-event
+  (re-frame/reg-event-db
     :test-event
     (fn [db [event-kw stack]]
       (throw (js/Error. "thrown in handler"))

src/re_frame/subs.cljc

@@ -22,7 +22,7 @@
     (re-frame/reg-event-fx
       ::later-test
       (fn [_world _event-v]
-        (re-frame/reg-event
+        (re-frame/reg-event-db
           ::watcher
           (fn [db [_ token]]
             (is (#{:event1 :event2 :event3} token) "unexpected: token passed through")

test/re-frame/event_test.cljs

@@ -0,0 +1,110 @@
+(ns re-frame.interceptor-test
+  (:require [cljs.test :refer-macros [is deftest]]
+            [reagent.ratom  :refer [atom]]
+            [re-frame.interceptor :refer [context get-coeffect assoc-effect assoc-coeffect get-effect
+                                          trim-v path on-changes
+                                          db-handler->interceptor fx-handler->interceptor]]))
+
+(enable-console-print!)
+
+(deftest test-trim-v
+  (let [c  (-> (context [:a :b :c] [])
+               ((:before trim-v)))]
+    (is (= (get-coeffect c :event)
+           [:b :c]))))
+
+
+(deftest test-one-level-path
+    (let [db   {:showing true :another 1}
+          p1   (path [:showing])]   ;; a simple one level path
+
+      (let [b4 (-> (context [] [] db)
+                  ((:before p1)))         ;; before
+            a (-> b4
+                  (assoc-effect :db false)
+                  ((:after p1)))]         ;; after
+
+        (is (= (get-coeffect b4 :db)      ;; test before
+               true))
+        (is (= (get-effect a :db)         ;; test after
+               {:showing false :another 1})))))
+
+
+(deftest test-two-level-path
+  (let [db  {:1 {:2 :target}}
+        p  (path [:1 :2])]    ;; a two level path
+
+    (let [b4 (-> (context [] [] db)
+                ((:before p)))           ;; before
+          a (-> b4
+                (assoc-effect :db :4)
+                ((:after p)))]           ;; after
+
+      (is (= (get-coeffect b4 :db))      ;; test before
+             :target)
+      (is (= (get-effect a :db)          ;; test after
+             {:1 {:2 :4}})))))
+
+
+(deftest test-db-handler-interceptor
+  (let [event   [:a :b]
+
+        handler (fn [db v]
+                  ;; make sure it was given the right arguements
+                  (is (= db :original-db-val))
+                  (is (= v event))
+                  ;; return a specific value for later checking
+                  :new-db-val)
+
+        i1      (db-handler->interceptor handler)
+        db      (-> (context event [] :original-db-val)
+                    ((:before i1))            ;; calls handler - causing :db in :effects to change
+                    (get-effect :db))]
+    (is (= db :new-db-val))))
+
+
+
+(deftest test-fx-handler-interceptor
+  (let [event   [:a :b]
+        coeffect {:db 4 :event event}
+        effect   {:db 5 :dispatch [:a]}
+
+        handler (fn [world v]
+                  ;; make sure it was given the right arguements
+                  (is (= world coeffect))
+                  (is (= v event))
+
+                  ;; return a specific value for later checking
+                  effect)
+
+        i1      (fx-handler->interceptor handler)
+        e       (-> (context event [] (:db coeffect))
+                    ((:before i1))            ;; call the handler
+                    (get-effect))]
+    (is (= e {:db 5 :dispatch [:a]}))))
+
+
+
+(deftest test-on-changes
+  (let [change-handler-i  (->  (fn [db v] (assoc db :a 10))
+                               db-handler->interceptor)
+
+        no-change-handler-i  (->  (fn [db v] db)
+                               db-handler->interceptor)
+
+        change-i   (on-changes + [:c] [:a] [:b])
+        orig-db    {:a 0 :b 2}]
+
+    (is (=  {:a 0 :b 2}
+            (-> (context [] [] orig-db)
+                ((:before no-change-handler-i))   ;; no change to :a and :b
+                ((:after change-i))
+                (get-effect :db))))
+    (is (=  {:a 10 :b 2 :c 12}
+            (-> (context [] [] orig-db)
+                ((:before change-handler-i))       ;; cause change to :a
+                ((:after change-i))
+                (get-effect :db))))))
+
+
+

test/re-frame/fx_test.cljs

@@ -5,7 +5,7 @@
     [jx.reporter.karma :as karma :include-macros true]
     [devtools.core :as devtools]
     ;; Test Namespaces -------------------------------
-    [re-frame.middleware-test]
+    [re-frame.interceptor-test]
     [re-frame.subs-test]
     [re-frame.fx-test]))
 
@@ -19,7 +19,7 @@
 
 (defn ^:export run-html-tests []
   (cljs-test/run-tests
-    're-frame.middleware-test
+    're-frame.interceptor-test
     're-frame.subs-test
     're-frame.fx-test))
 
@@ -28,6 +28,6 @@
 (defn ^:export run-karma [karma]
   (karma/run-tests
     karma
-    're-frame.middleware-test
+    're-frame.interceptor-test
     're-frame.subs-test
     're-frame.fx-test))