Create an interceptor from named arguments

Registers a function `f` to be called after each event is processed
 `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.

 This is useful in advanced cases like:
   - you are implementing a complex bootstrap pipeline
   - you want to create your own handling infrastructure, with perhaps multiple
     handlers for the one event, etc.  Hook in here.
   - libraries providing 'isomorphic javascript' rendering on  Nodejs or Nashorn.

'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.

returns an interceptor which runs a given function `f` in the `:after`
position, presumably for side effects.

`f` is called with two arguments: the `:effects` value for `:db`
(or the `coeffect` value of db if no db effect is returned) and the event.
Its return value is ignored, so `f` can only side-effect.

Examples use can be seen in the /examples/todomvc:
   - `f` runs schema validation (reporting any errors found).
   - `f` writes to localstorage.

Causes all subscriptions to be removed from the cache.
Does this by:
   1. running `on-dispose` on all cached subscriptions
   2. Each `on-dispose` will perform the removal of themselves.

This is for development time use. Useful when reloading Figwheel code
after a React exception, because React components won't have been
cleaned up properly. And this, in turn, means the subscriptions within those
components won't have been cleaned up correctly. So this forces the issue.

An interceptor which logs/instruments an event handler's actions to
`js/console.debug`. See examples/todomvc/src/events.cljs for use.

Output includes:
1. the event vector
2. a `clojure.data/diff` of db, before vs after, which shows
   the changes caused by the event handler.  You will absolutely have
   to understand https://clojuredocs.org/clojure.data/diff to
   understand the output.

You'd typically include this interceptor after (to the right of) any
path interceptor.

Warning:  calling clojure.data/diff on large, complex data structures
can be slow. So, you won't want this interceptor present in production
code. So condition it out like this :

    (re-frame.core/reg-event-db
       :evt-id
       [(when ^boolean goog.DEBUG re-frame.core/debug)]  ;; <-- conditional
       (fn [db v]
         ...))

To make this code fragment work, you'll also have to set goog.DEBUG to
false in your production builds - look in `project.clj` of /examples/todomvc.

Enqueue `event` for processing by event handling machinery.

`event` is a vector of length >= 1. The 1st element identifies the kind of event.

Note: 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 [:order-pizza {:supreme 2 :meatlovers 1 :veg 1})

Synchronously (immediately) process `event`. Do not queue.

Generally, don't use this. Instead use `dispatch`. It is an error
to use `dispatch-sync` within an event handler.

Useful when any delay in processing is a problem:
   1. the `:on-change` handler of a text field where we are expecting fast typing.
   2  when initialising your app - see 'main' in todomvc examples
   3. in a unit test where we don't want the action 'later'

Usage:
   (dispatch-sync [:sing :falsetto 634])

Add a collection of `interceptors` to the end of `context's` execution `:queue`.
Returns the updated `context`.

In an advanced case, this function could allow an interceptor to add new
interceptors to the `:queue` of a context.

Interceptor factory which runs the given function `f` in the `after handler`
position.  `f` is called with two arguments: `db` and `v`, and is expected to
return a modified `db`.

Unlike the `after` interceptor which is only about side effects, `enrich`
expects `f` to process and alter the given `db` coeffect in some useful way,
contributing to the derived data, flowing vibe.

Example Use:
------------

Imagine that todomvc needed to do duplicate detection - if any two todos had
the same text, then highlight their background, and report them via a warning
at the bottom of the panel.

Almost any user action (edit text, add new todo, remove a todo) requires a
complete reassessment of duplication errors and warnings. Eg: that edit
just made might have introduced a new duplicate, or removed one. Same with
any todo removal. So we need to re-calculate warnings after any CRUD events
associated with the todos list.

Unless we are careful, we might end up coding subtly different checks
for each kind of CRUD operation.  The duplicates check made after
'delete todo' event might be subtly different to that done after an
editing operation. Nice and efficient, but fiddly. A bug generator
approach.

So, instead, we create an `f` which recalculates ALL warnings from scratch
every time there is ANY change. It will inspect all the todos, and
reset ALL FLAGS every time (overwriting what was there previously)
and fully recalculate the list of duplicates (displayed at the bottom?).

https://twitter.com/nathanmarz/status/879722740776939520

By applying `f` in an `:enrich` interceptor, after every CRUD event,
we keep the handlers simple and yet we ensure this important step
(of getting warnings right) is not missed on any change.

We can test `f` easily - it is a pure function - independently of
any CRUD operation.

This brings huge simplicity at the expense of some re-computation
each time. This may be a very satisfactory trade-off in many cases.

Given an `id`, and an optional, arbitrary `value`, returns an interceptor
whose `:before` adds to the `:coeffects` (map) by calling a pre-registered
'coeffect handler' identified by the `id`.

The previous association of a `coeffect handler` with an `id` will have
happened via a call to `re-frame.core/reg-cofx` - generally on program startup.

Within the created interceptor, this 'looked up' `coeffect handler` will
be called (within the `:before`) with two arguments:
  - the current value of `:coeffects`
  - optionally, the originally supplied arbitrary `value`

This `coeffect handler` is expected to modify and return its first, `coeffects` argument.

Example Of how `inject-cofx` and `reg-cofx` work together
---------------------------------------------------------

1. Early in app startup, you register a `coeffect handler` for `:datetime`:

   (re-frame.core/reg-cofx
     :datetime                        ;; usage  (inject-cofx :datetime)
     (fn coeffect-handler
       [coeffect]
       (assoc coeffect :now (js/Date.))))   ;; modify and return first arg

2. Later, add an interceptor to an -fx event handler, using `inject-cofx`:

   (re-frame.core/reg-event-fx        ;; we are registering an event handler
      :event-id
      [ ... (inject-cofx :datetime) ... ]    ;; <-- create an injecting interceptor
      (fn event-handler
        [coeffect event]
        ... in here can access (:now coeffect) to obtain current datetime ... )))

Background
----------

`coeffects` are the input resources required by an event handler
to perform its job. The two most obvious ones are `db` and `event`.
But sometimes an event handler might need other resources.

Perhaps an event handler needs a random number or a GUID or the current
datetime. Perhaps it needs access to a DataScript database connection.

If an event handler directly accesses these resources, it stops being
pure and, consequently, it becomes harder to test, etc. So we don't
want that.

Instead, the interceptor created by this function is a way to 'inject'
'necessary resources' into the `:coeffects` (map) subsequently given
to the event handler at call time.

Checkpoints the state of re-frame and returns a function which, when
later called, will restore re-frame to that checkpointed state.

Checkpoint includes app-db, all registered handlers and all subscriptions.

Interceptor factory which acts a bit like `reaction`  (but it flows into
`db`, rather than out). It observes N paths within `db` and if any of them
test not identical? to their previous value  (as a result of a event handler
being run) then it runs `f` to compute a new value, which is then assoc-ed
into the given `out-path` within `db`.

Usage:

    (defn my-f
      [a-val b-val]
      ... some computation on a and b in here)

    (on-changes my-f [:c]  [:a] [:b])

Put this Interceptor on the right handlers (ones which might change :a or :b).
It will:
   - call `f` each time the value at path [:a] or [:b] changes
   - call `f` with the values extracted from [:a] [:b]
   - assoc the return value from `f` into the path  [:c]

returns an interceptor whose `:before` substitutes the coeffects `:db` with
a sub-path of `:db`. Within `:after` it grafts the handler's return value
back into db, at the right path.

So, its overall action is to make the event handler behave like the function
you might give to clojure's `update-in`.

Examples:

    (path :some :path)
    (path [:some :path])
    (path [:some :path] :to :here)
    (path [:some :path] [:to] :here)

Example Use:

    (reg-event-db
      :event-id
      (path [:a :b])  ;; used here, in interceptor chain
      (fn [b v]       ;; 1st arg is now not db. Is the value from path [:a :b] within db
        ... new-b))   ;; returns a new value for that path (not the entire db)

Notes:
  1. `path` may appear more than once in an interceptor chain. Progressive narrowing.
  2. if `:effects` contains no `:db` effect, can't graft a value back in.

Remove all events queued for processing

Register the given coeffect `handler` for the given `id`, for later use
within `inject-cofx`.

`id` is keyword, often namespaced.
`handler` is a function which takes either one or two arguements, the first of which is
always `coeffects` and which returns an updated `coeffects`.

See the docs for `inject-cofx` for example use.

Register the given event `handler` (function) for the given `id`. Optionally, provide
an `interceptors` chain.
`id` is typically a namespaced keyword  (but can be anything)
`handler` is a function: (context-map event-vector) -> context-map

This form of registration is almost never used. 

Register the given event `handler` (function) for the given `id`. Optionally, provide
an `interceptors` chain.
`id` is typically a namespaced keyword  (but can be anything)
`handler` is a function: (db event) -> db
`interceptors` is a collection of interceptors. Will be flattened and nils removed.
`handler` is wrapped in its own interceptor and added to the end of the interceptor
 chain, so that, in the end, only a chain is registered.
 Special effects and coeffects interceptors are added to the front of this
 chain.

Register the given event `handler` (function) for the given `id`. Optionally, provide
an `interceptors` chain.
`id` is typically a namespaced keyword  (but can be anything)
`handler` is a function: (coeffects-map event-vector) -> effects-map
`interceptors` is a collection of interceptors. Will be flattened and nils removed.
`handler` is wrapped in its own interceptor and added to the end of the interceptor
 chain, so that, in the end, only a chain is registered.
 Special effects and coeffects interceptors are added to the front of the
 interceptor chain.  These interceptors inject the value of app-db into coeffects,
 and, later, action effects.

Register the given effect `handler` for the given `id`.

`id` is keyword, often namespaced.
`handler` is a side-effecting function which takes a single argument and whose return
value is ignored.

Example Use
-----------

First, registration ... associate `:effect2` with a handler.

(reg-fx
   :effect2
   (fn [value]
      ... do something side-effect-y))

Then, later, if an event handler were to return this effects map ...

{...
 :effect2  [1 2]}

 ... then the `handler` `fn` we registered previously, using `reg-fx`, will be
 called with an argument of `[1 2]`.

For a given `query-id`, register two functions: a `computation` function and an `input signals` function.

 During program execution, a call to `subscribe`, such as `(subscribe [:sub-id 3 "blue"])`,
 will create a new `:sub-id` node in the Signal Graph. And, at that time, re-frame
 needs to know how to create the node.   By calling `reg-sub`, you are registering
 'the template' or 'the mechanism' by which nodes in the Signal Graph can be created.

 Repeating: calling `reg-sub` does not create a node. It only creates the template
 from which nodes can be created later.

 `reg-sub` arguments are:
   - a `query-id` (typically a namespaced keyword)
   - a function which returns the inputs required by this kind of node (can be supplied  in one of three ways)
   - a function which computes the value of this kind of node

 The `computation function` is always the last argument supplied and it is expected to have the signature:
   `(input-values, query-vector) -> a-value`

 When `computation function` is called, the `query-vector` argument will be the vector supplied to the
 the `subscribe` which caused the node to be created. So, if the call was `(subscribe [:sub-id 3 "blue"])`,
 then the `query-vector` supplied to the computaton function will be `[:sub-id 3 "blue"]`.

 The arguments supplied between the `query-id` and the `computation-function` can vary in 3 ways,
 but whatever is there defines the `input signals` part of the template, controlling what input
values "flow into" the `computation function` gets when it is called.

 `reg-sub` can be called in one of three ways, because there are three ways to define the input signals part.
 But note, the 2nd method, in which a `signal-fn` is explicitly supplied, is the most canonical and instructive. The other
 two are really just sugary variations.

 1. No input signals given:
     ```clj
    (reg-sub
      :query-id
      a-computation-fn)   ;; has signature:  (fn [db query-vec]  ... ret-value)
    ```

    In the absence of an explicit `input-fn`, the node's input signal defaults to `app-db`
    and, as a result, the value within `app-db` (a map) is
    is given as the 1st argument when `a-computation-fn` is called.


 2. A signal function is explicitly supplied:
    ```clj
    (reg-sub
      :query-id
      signal-fn     ;; <-- here
      computation-fn)
    ```

    This is the most canonical and instructive of the three variations.

    When a node is created from the template, the `signal-fn` will be called and it
    is expected to return the input signal(s) as either a singleton, if there is only
    one, or a sequence if there are many, or a map with the signals as the values.

    The values from returned nominated signals will be supplied as the 1st argument to
    the `a-computation-fn` when it is called - and subject to what this `signal-fn` returns,
    this value will be either a singleton, sequence or map of them (paralleling
    the structure returned by the `signal-fn`).

    This example `signal-fn` returns a vector of input signals.
      ```clj
      (fn [query-vec dynamic-vec]
        [(subscribe [:a-sub])
         (subscribe [:b-sub])])
      ```
    The associated computation function must be written
    to expect a vector of values for its first argument:
      ```clj
      (fn [[a b] query-vec]     ;; 1st argument is a seq of two values
        ....)
       ```

    If, on the other hand, the signal function was simpler and returned a singleton, like this:
       ```clj
       (fn [query-vec dynamic-vec]
         (subscribe [:a-sub]))
       ```
    then the associated computation function must be written to expect a single value
    as the 1st argument:
       ```clj
       (fn [a query-vec]       ;; 1st argument is a single value
         ...)
       ```

    Further Note: variation #1 above, in which an `input-fn` was not supplied, like this:
      ```clj
    (reg-sub
      :query-id
      a-computation-fn)   ;; has signature:  (fn [db query-vec]  ... ret-value)
    ```
    is the equivalent of using this
    2nd variation and explicitly suppling a `signal-fn` which returns `app-db`:
    ```clj
    (reg-sub
      :query-id
      (fn [_ _]  re-frame/app-db)   ;; <--- explicit input-fn
      a-computation-fn)             ;; has signature:  (fn [db query-vec]  ... ret-value)
    ```

 3. Syntax Sugar

    ```clj
    (reg-sub
      :a-b-sub
      :<- [:a-sub]
      :<- [:b-sub]
      (fn [[a b] query-vec]    ;; 1st argument is a seq of two values
        {:a a :b b}))
    ```

    This 3rd variation is just syntactic sugar for the 2nd.  Instead of providing an
    `signals-fn` you provide one or more pairs of `:<-` and a subscription vector.

    If you supply only one pair a singleton will be supplied to the computation function,
    as if you had supplied a `signal-fn` returning only a single value:

    ```clj
    (reg-sub
      :a-sub
      :<- [:a-sub]
      (fn [a query-vec]      ;; only one pair, so 1st argument is a single value
        ...))
    ```

 For further understanding, read `/docs`, and look at the detailed comments in
 /examples/todomvc/src/subs.cljs
 

This is a low level, advanced function.  You should probably be
using reg-sub instead.
Docs in https://github.com/day8/re-frame/blob/master/docs/SubscriptionFlow.md

Change the set (or a subset) of logging functions used by re-frame.
`new-loggers` should be a map with the same keys as `loggers` (above)

Given a `query` vector, returns a Reagent `reaction` which, over
time, reactively delivers a stream of values. So in FRP-ish terms,
it returns a `Signal`.

To obtain the returned Signal/Stream's current value, it must be `deref`ed.

`query` is a vector of at least one element. The first element is the
`query-id`, typically a namespaced keyword. The rest of the vector's
elements are optional, additional values which parameterise the query
performed.

`dynv` is an optional 3rd argument, which is a vector of further input
signals (atoms, reactions, etc), NOT values. This argument exists for
historical reasons and is borderline deprecated these days.

Example Usage:
--------------

  (subscribe [:items])
  (subscribe [:items "blue" :small])
  (subscribe [:items {:colour "blue"  :size :small}])

Note: for any given call to `subscribe` there must have been a previous call
to `reg-sub`, registering the query handler (function) for the `query-id` given.

Hint
----

When used in a view function BE SURE to `deref` the returned value.
In fact, to avoid any mistakes, some prefer to define:

   (def <sub  (comp deref re-frame.core/subscribe))

And then, within their views, they call  `(<sub [:items :small])` rather
than using `subscribe` directly.

An interceptor which removes the first element of the event vector,
allowing you to write more aesthetically pleasing event handlers. No
leading underscore on the event-v!
Your event handlers will look like this:

    (defn my-handler
      [db [x y z]]    ;; <-- instead of [_ x y z]
      ....)