Effects (fx) system - side effect handlers.
Ported from re-frame/fx.cljc with JVM compatibility.
Effects are declarative descriptions of side effects. Each effect type has a registered handler that performs the actual work.
Built-in effects:
Usage: ;; Register a custom effect handler (reg-fx :http (fn [{:keys [method url on-success]}] (http-request method url (fn [response] (dispatch [on-success response])))))
;; Event handler returns effects map (reg-event-fx :user/login (fn [{:keys [db]} [_ credentials]] {:db (assoc db :loading? true) :http {:method :post :url "/api/login" :body credentials}}))
Effects (fx) system - side effect handlers.
Ported from re-frame/fx.cljc with JVM compatibility.
Effects are declarative descriptions of side effects.
Each effect type has a registered handler that performs the actual work.
Built-in effects:
- :db - Update application state
- :dispatch - Dispatch another event
- :dispatch-n - Dispatch multiple events
Usage:
;; Register a custom effect handler
(reg-fx :http
(fn [{:keys [method url on-success]}]
(http-request method url
(fn [response]
(dispatch [on-success response])))))
;; Event handler returns effects map
(reg-event-fx :user/login
(fn [{:keys [db]} [_ credentials]]
{:db (assoc db :loading? true)
:http {:method :post :url "/api/login" :body credentials}}))Dynamic var for intercepting effect execution.
When bound to a function, do-fx-seq calls this instead of executing effects directly.
Used by run-sub-fsm-fx to capture child effects without executing them (thread-safe).
Default: nil (effects execute normally).
Dynamic var for intercepting effect execution. When bound to a function, `do-fx-seq` calls this instead of executing effects directly. Used by `run-sub-fsm-fx` to capture child effects without executing them (thread-safe). Default: nil (effects execute normally).
(clear-fx)(clear-fx id)Clear effect handler. If no id provided, clear all.
Clear effect handler. If no id provided, clear all.
(clear-fx-executor!)Restore the default effect-invocation policy. Returns nil.
Restore the default effect-invocation policy. Returns nil.
(default-invoke-fx-handler effect-id effect-value)Look up and invoke a registered fx handler for a single effect. Logs a warning if no handler is registered, catches and logs exceptions. Never throws.
This is the DEFAULT policy. set-fx-executor! replaces it.
Look up and invoke a registered fx handler for a single effect. Logs a warning if no handler is registered, catches and logs exceptions. Never throws. This is the DEFAULT policy. `set-fx-executor!` replaces it.
(do-fx effects)Execute all effects in an effects map.
:db runs first when present; the rest run in undefined order. Unknown
effects are warned about and do not throw.
Every effect, :db included, goes through the installed fx executor
(set-fx-executor!), so an embedder's metrics and unregistered-effect
counters see the whole set rather than all of it except :db.
Execute all effects in an effects map. `:db` runs first when present; the rest run in undefined order. Unknown effects are warned about and do not throw. Every effect, `:db` included, goes through the installed fx executor (`set-fx-executor!`), so an embedder's metrics and unregistered-effect counters see the whole set rather than all of it except `:db`.
(do-fx-seq effects)Execute effects from a sequential collection of [effect-id value] tuples.
Unlike do-fx (which takes a map), this preserves ordering and allows
the same effect-id to appear multiple times.
Used by the FSM engine when handlers return {:data ... :fx [...]}.
When *fx-interceptor* is bound, delegates to it instead of executing
effects directly. This enables sub-FSM effect capture (thread-safe).
Example: (do-fx-seq [[:log {:msg "starting"}] [:http {:url "/api"}] [:log {:msg "done"}]])
Execute effects from a sequential collection of [effect-id value] tuples.
Unlike `do-fx` (which takes a map), this preserves ordering and allows
the same effect-id to appear multiple times.
Used by the FSM engine when handlers return `{:data ... :fx [...]}`.
When `*fx-interceptor*` is bound, delegates to it instead of executing
effects directly. This enables sub-FSM effect capture (thread-safe).
Example:
(do-fx-seq [[:log {:msg "starting"}]
[:http {:url "/api"}]
[:log {:msg "done"}]])(fx-executor-installed?)True when a non-default effect-invocation policy is installed.
True when a non-default effect-invocation policy is installed.
(reg-fx id handler)Register an effect handler.
(reg-fx :effect-id (fn [effect-value] ;; perform side effect ))
Effect handlers:
Register an effect handler.
(reg-fx :effect-id
(fn [effect-value]
;; perform side effect
))
Effect handlers:
- Receive the effect value from the effects map
- Perform the side effect
- Return value is ignored(registered-fx-ids)Return set of registered effect handler IDs.
Return set of registered effect handler IDs.
(registry-snapshot)Current effect registry value. For inspection and save/restore in tests.
Current effect registry value. For inspection and save/restore in tests.
(restore-registry! handlers)Replace the whole effect registry with handlers. For test isolation.
Replace the whole effect registry with `handlers`. For test isolation.
(set-fx-executor! f)Install f as the policy that invokes ONE effect: (f effect-id effect-value).
The policy owns handler lookup and error handling, so an embedder can add
metrics, tracing or a loud-fail counter for unregistered effects without the
library knowing what any of those are. default-invoke-fx-handler is the
behaviour to fall back on, and a policy that wants only to observe should
call it.
A policy MUST NOT throw: do-fx runs after the interceptor chain has
already committed, so a throw here surfaces as a dispatch failure for work
that already happened.
Returns f. One executor at a time, last writer wins.
Install `f` as the policy that invokes ONE effect: (f effect-id effect-value). The policy owns handler lookup and error handling, so an embedder can add metrics, tracing or a loud-fail counter for unregistered effects without the library knowing what any of those are. `default-invoke-fx-handler` is the behaviour to fall back on, and a policy that wants only to observe should call it. A policy MUST NOT throw: `do-fx` runs after the interceptor chain has already committed, so a throw here surfaces as a dispatch failure for work that already happened. Returns `f`. One executor at a time, last writer wins.
(unreg-fx id)Remove effect handler for fx-id. Returns true if the handler was found and removed, false if not found. Thread-safe (uses swap! on atom).
Remove effect handler for fx-id. Returns true if the handler was found and removed, false if not found. Thread-safe (uses swap! on atom).
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 |