Async coeffects (acofx) for re-frame: input an event needs from the outside world that only arrives asynchronously -- a backend request, an IPC call, an async browser API.
Register a handler with reg-acofx, or reuse an existing effect with
reg-acofx-by-fx, and inject it into an event with inject-acofx
or inject-acofxs. The event handler then runs once, with every acofx
value in its coeffects, instead of a chain of load, success and
further events.
Async coeffects (acofx) for re-frame: input an event needs from the outside world that only arrives asynchronously -- a backend request, an IPC call, an async browser API. Register a handler with [[reg-acofx]], or reuse an existing effect with [[reg-acofx-by-fx]], and inject it into an event with [[inject-acofx]] or [[inject-acofxs]]. The event handler then runs once, with every acofx value in its coeffects, instead of a chain of load, success and further events.
(inject-acofx id)(inject-acofx id value)(inject-acofx id value {:keys [on-failure inject-key]})Returns an interceptor that injects the single async coeffect id,
with value and opts as described in inject-acofxs.
Returns an interceptor that injects the single async coeffect `id`, with `value` and `opts` as described in [[inject-acofxs]].
(inject-acofxs acofxs-by-inject-key)(inject-acofxs & acofxs)Returns an interceptor that injects the async coeffects acofxs into
the event's coeffects. They run concurrently; the event handler runs
once all of them are done.
Each of acofxs is a vector [id value opts] of an acofx registered
with reg-acofx, the optional value for its handler -- like
re-frame's inject-cofx -- and an optional map of
:inject-key -- the key in the coeffects, defaults to id. Needed
to inject the same acofx more than once.:on-failure -- event to dispatch on failure, the exception
appended.Instead, acofxs may be a single map of inject key to [id value opts]. Its keys replace :inject-key; giving both throws.
On failure the event handler does not run. The event dispatched is the
one the acofx handler named (see reg-acofx), else the injection's
:on-failure, else the global one (see
set-global-on-failure-event). Without any, the failure is logged.
The event runs twice -- once to start the acofxs, once with their
values (once more per further injection on the same event).
Interceptors before this one see every run; their :afters run on
the aborted ones too, with no effects to act on.
(rf/reg-event-fx ::init-view
[(inject-acofxs
[::http {:uri "/a"} {:inject-key :a}]
[::http {:uri "/b"} {:inject-key :b}])]
(fn [{:keys [db a b]} _]
{:db (assoc db ::a a, ::b b)}))
;; the same, keyed by a map
(inject-acofxs
{:a [::http {:uri "/a"}]
:b [::http {:uri "/b"}]})
Returns an interceptor that injects the async coeffects `acofxs` into
the event's coeffects. They run concurrently; the event handler runs
once all of them are done.
Each of `acofxs` is a vector `[id value opts]` of an acofx registered
with [[reg-acofx]], the optional `value` for its handler -- like
re-frame's `inject-cofx` -- and an optional map of
- `:inject-key` -- the key in the coeffects, defaults to `id`. Needed
to inject the same acofx more than once.
- `:on-failure` -- event to dispatch on failure, the exception
appended.
Instead, `acofxs` may be a single map of inject key to `[id value
opts]`. Its keys replace `:inject-key`; giving both throws.
On failure the event handler does not run. The event dispatched is the
one the acofx handler named (see [[reg-acofx]]), else the injection's
`:on-failure`, else the global one (see
[[set-global-on-failure-event]]). Without any, the failure is logged.
The event runs twice -- once to start the acofxs, once with their
values (once more per further injection on the same event).
Interceptors before this one see every run; their `:after`s run on
the aborted ones too, with no effects to act on.
(rf/reg-event-fx ::init-view
[(inject-acofxs
[::http {:uri "/a"} {:inject-key :a}]
[::http {:uri "/b"} {:inject-key :b}])]
(fn [{:keys [db a b]} _]
{:db (assoc db ::a a, ::b b)}))
;; the same, keyed by a map
(inject-acofxs
{:a [::http {:uri "/a"}]
:b [::http {:uri "/b"}]})Registrar kind of acofx handlers, see reg-acofx.
Registrar kind of acofx handlers, see [[reg-acofx]].
(reg-acofx id handler)Registers handler as async coeffect (acofx) under id, for use with
inject-acofx and inject-acofxs.
handler is called with the event's coeffects and the injection:
the options map given to inject-acofxs, with :id, :value and
:inject-key filled in. The :value is the handler's to interpret,
as with re-frame's inject-cofx. It returns a promise channel
carrying the value to inject. A failure travels as an exception over
that channel, see jtk-dvlp.async.
To name the event to dispatch on failure, put it under ::on-failure
into the ex-data of that exception. Without one, the injection's
:on-failure applies, then the global one -- so a handler that wants
to defer to the injection leaves it out, and one that wants to
override takes the injection's into account itself.
(reg-acofx ::now
(fn [_coeffects {delay-ms :value}]
(go
(<! (timeout delay-ms))
(js/Date.))))
Registers `handler` as async coeffect (acofx) under `id`, for use with
[[inject-acofx]] and [[inject-acofxs]].
`handler` is called with the event's `coeffects` and the injection:
the options map given to [[inject-acofxs]], with `:id`, `:value` and
`:inject-key` filled in. The `:value` is the handler's to interpret,
as with re-frame's `inject-cofx`. It returns a promise channel
carrying the value to inject. A failure travels as an exception over
that channel, see `jtk-dvlp.async`.
To name the event to dispatch on failure, put it under `::on-failure`
into the `ex-data` of that exception. Without one, the injection's
`:on-failure` applies, then the global one -- so a handler that wants
to defer to the injection leaves it out, and one that wants to
override takes the injection's into account itself.
(reg-acofx ::now
(fn [_coeffects {delay-ms :value}]
(go
(<! (timeout delay-ms))
(js/Date.))))(reg-acofx-by-fx id
{:keys [fx-id initial-args on-success-key on-failure-key
on-failure-event]})Registers the effect fx-id as acofx under id, so an effect that
reports its result through events (e.g. :http-xhrio) can be injected
like any other acofx.
initial-args is the effect's base configuration: a map, or a
function that is called with the event's coeffects and the event
and returns that map.on-success-key is the effect's key for the success event.on-failure-key is the effect's key for the failure event
(optional; without it a failure is never noticed).on-failure-event is the event to dispatch on failure (optional).
An :on-failure given at injection replaces it.The value given at injection configures the effect for that
injection:
initial-args,coeffects, the event and the
resolved initial-args, and what it returns replaces them -- so it
can derive from the registered configuration, down to removing
keys.WATCHOUT: Only the first argument the effect hands to its success or
failure event is taken as result -- that is what :http-xhrio and
most effects use. The failure's argument ends up under :error in the
ex-data of the exception.
Registers the effect `fx-id` as acofx under `id`, so an effect that reports its result through events (e.g. `:http-xhrio`) can be injected like any other acofx. - `initial-args` is the effect's base configuration: a map, or a function that is called with the event's `coeffects` and the event and returns that map. - `on-success-key` is the effect's key for the success event. - `on-failure-key` is the effect's key for the failure event (optional; without it a failure is never noticed). - `on-failure-event` is the event to dispatch on failure (optional). An `:on-failure` given at injection replaces it. The `value` given at injection configures the effect for that injection: - a map is merged over `initial-args`, - a function is called with the `coeffects`, the event and the resolved `initial-args`, and what it returns replaces them -- so it can derive from the registered configuration, down to removing keys. WATCHOUT: Only the first argument the effect hands to its success or failure event is taken as result -- that is what `:http-xhrio` and most effects use. The failure's argument ends up under `:error` in the `ex-data` of the exception.
(set-global-on-failure-event on-failure)Sets the event to dispatch when an acofx fails and neither the
handler nor the injection names one, see inject-acofxs. nil
removes it again.
Sets the event to dispatch when an acofx fails and neither the handler nor the injection names one, see [[inject-acofxs]]. `nil` removes it again.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |