Carry

ClojureScript single-page application framework inspired by re-frame, Elm Architecture, Redux and Cerebral.

Carry provides a structure for making GUI application code easier to modify, debug, test and be worked on by multiple programmers.

The core of the framework is a simple state management library. UI bindings, routing, debugger, etc. are implemented as separate optional packages.

Stable. Was used in production.

I now focus on the successor Aide framework instead.

• Functional API without globals and macros.
• Agnostic to UI layer: can be effectively used with Reagent (via carry-reagent package) or any other view layer that is able to re-render UI in response to app model changes.
• Time traveling debugger inspired by Redux DevTools and Cerebral Debugger.
• Live code editing using Figwheel and debugger's replay mode.
• Can work with Devcards.
• Core library can be also used in Clojure projects.

Carry enforces:

• Separation of presentation code.
• Events as first-class citizens.
• Splitting event handling code into side-effectful and "pure" model updating phases.
• Storing model in a single observable atom.

It also advises to decouple view and view model code in the presentation layer:

• An app is defined by its initial model value, signal handler and action handler.
• All app state is stored inside a single model atom.
• Anyone can read model value at any given time and subscribe to its changes.
• Signal handler performs side effects and dispatches actions.
• Anyone can dispatch a new signal: signal handler, views, timers, etc.
• Typically UI layer dispatches signals on UI events and subscribes to model changes to redraw the GUI when needed.
• Model can be modified only by dispatching actions.
• Only signal handler can dispatch actions.
• Action handler is a pure function which returns a new model value based on an incoming action.

Demo, Source code

HTML:

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Carry • Counter</title>
    <link rel="icon" href="data:;base64,iVBORw0KGgo=">
</head>
<body>
    <div id="root"></div>
    <script src="js/compiled/frontend.js" type="text/javascript"></script>
</body>
</html>

Main file:

(ns app.core
  (:require [counter.core :as counter]
            [carry.core :as carry]
            [carry-reagent.core :as carry-reagent]
            [reagent.core :as r]))

(let [app (carry/app counter/blueprint)
      [_ app-view] (carry-reagent/connect app counter/view-model counter/view)]
    (r/render app-view (.getElementById js/document "root"))
    ((:dispatch-signal app) :on-start))

UI (using Reagent and carry-reagent):

(ns counter.core
  (:require [cljs.core.match :refer-macros [match]]
            [reagent.ratom :refer [reaction]]))

(defn view-model
  [model]
  {:counter (reaction (str "#" (:val @model)))})

(defn view
  [{:keys [counter] :as _view-model} dispatch]
  [:p
   @counter " "
   [:button {:on-click #(dispatch :on-increment)} "+"] " "
   [:button {:on-click #(dispatch :on-decrement)} "-"] " "
   [:button {:on-click #(dispatch :on-increment-if-odd)} "Increment if odd"] " "
   [:button {:on-click #(dispatch :on-increment-async)} "Increment async"]])

Blueprint:

(def -initial-model {:val 0})

(defn -on-signal
  [model signal _dispatch-signal dispatch-action]
  (match signal
         :on-start nil
         :on-stop nil

         :on-increment
         (dispatch-action :increment)

         :on-decrement
         (dispatch-action :decrement)

         :on-increment-if-odd
         (when (odd? (:val @model))
           (dispatch-action :increment))

         :on-increment-async
         (.setTimeout js/window #(dispatch-action :increment) 1000)))

(defn -on-action
  [model action]
  (match action
         :increment (update model :val inc)
         :decrement (update model :val dec)))

(def blueprint {:initial-model -initial-model
                :on-signal     -on-signal
                :on-action     -on-action})

• carry-reagent (bindings for Reagent)

• carry-atom-sync (creating a bidirectional sync between an app model and a specified atom-like reference)
• carry-debugger (time traveling debugger)
• carry-history (working with browser history)
• carry-logging (console logging)
• carry-persistence (automatic model saving/loading using browser storage)
• carry-schema (model validation using Schema)

More information can be found at the project site:

• User Guide
• Examples
• API Reference
• FAQ
• Developer Guide

Copyright © 2016 Yuri Govorushchenko.

Released under an MIT license.