jtk-dvlp.re-frame.async-coeffects — net.clojars.jtkdvlp/re-frame-async-coeffects 2.0.0

inject-acofx cljs

(inject-acofx acofx)

(inject-acofx acofx {:keys [error-dispatch] :as opts})

Given an async-coeffect (acofx) returns an interceptor whose :before adds to the :coeffects (map) by calling a pre-registered 'async coeffect handler' identified by id.

As first argument give the id of the acofx or an vector of id and args. args can be mixed of any val and fns. fns will be applied with coeffects and event. Computed args prepended with coeffects will be applied to acofx handler.

As second optional argument give a map of options to carry a :error-dispatch vector, see also set-global-error-dispatch. error-dispatch will be called on error, event will be aborted.

The previous association of a async coeffect handler with an id will have happened via a call to reg-acofx - generally on program startup. See also reg-acofx-by-fx to reuse effects as coeffects.

Within the created interceptor, this 'looked up' async coeffect handler will be called (within the :before) with arguments:

• the current value of :coeffects
• optionally, the given or computed args by args

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

Example of inject-acofx and reg-acofx working together

First - Early in app startup, you register a async coeffect handler for :async-now:

#!clj
(reg-acofx
  :async-now                        ;; usage  (inject-acofx :async-now)
  (fn async-coeffect-handler
    [coeffect]
    (go
      (<! (timeout 1000))
      (assoc coeffect :async-now (js/Date.)))))   ;; modify and return first arg

Second - Later, add an interceptor to an -fx event handler, using inject-acofx:

#!clj
(re-frame.core/reg-event-fx            ;; when registering an event handler
  :event-id
  [ ... (inject-acofx :async-now) ... ]  ;; <-- create an injecting interceptor
  (fn event-handler
    [coeffect event]
      ;;... in here can access (:async-now coeffect) to obtain current async-now ...
    )))

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 maybe async resources.

Perhaps an event handler needs data from backend or some other async api.

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.

See also reg-acofx

inject-acofxs cljs

(inject-acofxs acofxs)

(inject-acofxs acofxs {:keys [error-dispatch] :as opts})

Give as much acofxs as you want as vector or map to compute async (pseudo parallel) values. Use map keys to rename keys within event coeffects map. For further reading see inject-acofx.

kind cljs

reg-acofx cljs

(reg-acofx id handler)

Register the given async-coeffect handler for the given id, for later use within inject-acofx:

• id is keyword, often namespaced.
• handler is a function which takes either one or more arguements, the first of which is always coeffects and which returns an updated coeffects as cljs.core.async/chan.

See also: inject-acofx

reg-acofx-by-fx cljs

(reg-acofx-by-fx id fx on-success-key & [on-error-key fx-map])

Register the given effect fx as coeffect for the given id, for later use within inject-acofx:

• id is keyword, often namespaced.
• fx is the effect id to use as coeffect.
• on-success-key is the key of fx to register a success event vector.
• on-error-key is the key of fx to register a error event vector (optional).
• fx-map is a predefined map to configure the fx as the fx supports

See also: inject-acofx

set-global-error-dispatch! cljs

Sets global error dispatch.