re-frame-async-flow-fx

The library is built on the principle that managing asynchronous task flow is equivalent to managing a state machine. To handle async flows effectively, you need three components:

1. Retained State: Data describing the current progress of the flow.
2. Events: Triggers (FSM triggers) that announce when something has happened or failed.
3. Transition Rules: A set of rules that define how the application state transitions and what further activity is triggered when events arrive.

Unlike approaches like redux-saga which encode state machines into imperative code (using generators), re-frame-async-flow-fx adopts a data-driven approach. This follows the Clojure preference for "programming in data," allowing for more complex state machines (including failure states and cascades) to be managed via data tables rather than messy, nested imperative logic.

You can enable detailed console logging to debug complex flows using two methods:

1. Globally: Call (async-flow-fx/enable-debug? true) in your top-level events namespace.
2. Per-flow: Add the :debug? true property to your flow definition map.

When debugging, it is recommended to provide an :id in your flow map to differentiate log entries when multiple flows are active.

;; Global enablement
(async-flow-fx/enable-debug? true)

;; Per-flow enablement
{:id :my-flow-id
 :debug? true
 :first-dispatch [:init]
 :rules [...]}

The library uses standard cljs.test.

To run tests in a browser:

lein watch

To run tests with Karma:

npm install karma-cli -g
lein ci

# Browser
lein watch

# Karma
npm install karma-cli -g
lein ci

Add day8.re-frame/async-flow-fx as a project dependency. This library requires re-frame >= 0.8.0.

;; Add to your project dependencies (e.g., in deps.edn or project.clj)
[day8.re-frame/async-flow-fx "0.4.0"]

In your application's main entry function, use dispatch-sync to trigger the initial boot event (e.g., [:boot]).

Using dispatch-sync instead of dispatch ensures that the application database (app-db) is synchronously initialized before mounting components or views that subscribe to that state. This prevents views from attempting to render with uninitialized state.

(defn ^:export main
  []
  (dispatch-sync [:boot])            ;; <--- boot process is started
  (reagent/render
    [this-app.views/main]
    (.getElementById js/document "app")))

To enable the :async-flow effect handler in re-frame, you must include a require for day8.re-frame.async-flow-fx in your event registration namespace (e.g., events.cljs). Even if you do not call any functions from the library directly, the mere presence of this require causes the effect handler to self-register with re-frame.

(ns app.events
  (:require
    [day8.re-frame.async-flow-fx :as async-flow-fx] ;; <-- required for self-registration
    ...))

For complex logic where you need to inspect the data carried within an event, use functions for :events (as a predicate) or for :dispatch-fn.

Example: Dispatching based on event data If a file upload success event returns an ID, use :dispatch-fn to pass that ID to the next event:

{:when :seen? :events :upload/success
 :dispatch-fn (fn [[e id]] [[:remote/file-uploaded id]])}

Example: Using a predicate to filter events To dispatch a server error only when an HTTP response status is 500 or higher:

{:when :seen? :events (fn [[e status]] (and (= e :http/response-received) (>= status 500)))
 :dispatch [:server/error]}

Register an event handler using reg-event-fx for your boot event. The handler should perform synchronous state updates (via the :db key) and then trigger the asynchronous flow by returning the :async-flow key containing your flow definition.

(reg-event-fx                    ;; note the -fx
  :boot                          ;; usage: (dispatch [:boot])
  (fn [_ _]
    {:db (-> {}                  ;; synchronous work
            task1-fn
            task2-fn)            ;; e.g. setting loading state
     :async-flow (boot-flow)}))   ;; kick off the async process

In an async flow, you may want to dispatch events that serve only as signals and do not require a registered re-frame handler. To avoid re-frame warnings about unregistered events, use the built-in no-op handler ::async-flow-fx/notify within your event sequence.

;; Using notify to signal a success event without needing a dedicated handler
{:when :seen? :events [[::async-flow-fx/notify :success-db-connect]]   
 :dispatch-n '([:do-query-user] [:do-query-site-prefs])}

[{:when :seen? :events [[::async-flow-fx/notify :success-db-connect]]   
  :dispatch-n '([:do-query-user] [:do-query-site-prefs])}
 ...}]