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

inject-acofx cljs

(inject-acofx & [map-or-acofx :as acofxs])

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

Give as much acofxs as you want to compute async (pseudo parallel) values via id of the acofx or an vector of id and a seq of args or id, args-fn and args. args will be applied to acofx handler unless give args-fn, then args will be applied to args-fn. Result of args-fn will be applied to acofx-handler. Both acofx-handler and args-fn first argument will be coeffects map.

Give a map instead of multiple acofxs like {:acofxs ...} to carry a :error-dispatch vector. error-dispatch will be called on error of any acofxs, event will be aborted. :acofxs can be given as vector or map. Use map keys to rename keys within event coeffects map.

The previous association of a async coeffect handler with an id will have happened via a call to reg-acofx - generally on program startup.

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 or args-fn

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-datetime:

#!clj
(reg-acofx
  :async-datetime                        ;; usage  (inject-acofx :async-datetime)
  (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-datetime) ... ]  ;; <-- create an injecting interceptor
  (fn event-handler
    [coeffect event]
      ;;... in here can access (:async-now coeffect) to obtain current async-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 maybe async resources.

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

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

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