Flows (#25)

* Initial, basic Flows implementation

* Updated label

* Improved current Flow tests to span entire data loop

* Added flow execution on registration and de-duped registrations

* Added support for layered / dependent flows using dependency graph

* Added ability so subscribe to a Flow

* Added Flow lifecycle support and updated samples/flow to demo

* Fixed indentation and added link to kahn gist

* Added core, alpha namespaces, moved Flows to alpha, added deprecations

* Fixed tests

* Added docs

* Updated docs

README.md

@@ -14,13 +14,14 @@ A [ClojureDart](https://github.com/Tensegritics/ClojureDart) framework, inspired
 * Interact with global state via events & subscriptions
 * Handle side effects at the edge with effect handlers
 * Familiar api if coming from re-frame
-  * [Event Dispatch](http://day8.github.io/re-frame/a-loop/#1st-domino-event-dispatch)
-  * [Event Handling](http://day8.github.io/re-frame/a-loop/#2nd-domino-event-handling)
-    * [Coeffects](http://day8.github.io/re-frame/Coeffects/)
-    * [Interceptors](http://day8.github.io/re-frame/Interceptors/)
-  * [Effect Handling](http://day8.github.io/re-frame/a-loop/#3rd-domino-effect-handling)
-  * [Signal Graph](http://day8.github.io/re-frame/a-loop/#domino-4-query)
-  * [Subscriptions](http://day8.github.io/re-frame/a-loop/#domino-5-view)
+  * [Event Dispatch](https://day8.github.io/re-frame/a-loop/#1st-domino-event-dispatch)
+  * [Event Handling](https://day8.github.io/re-frame/a-loop/#2nd-domino-event-handling)
+    * [Coeffects](https://day8.github.io/re-frame/Coeffects/)
+    * [Interceptors](https://day8.github.io/re-frame/Interceptors/)
+  * [Effect Handling](https://day8.github.io/re-frame/a-loop/#3rd-domino-effect-handling)
+  * [Signal Graph](https://day8.github.io/re-frame/a-loop/#domino-4-query)
+  * [Subscriptions](https://day8.github.io/re-frame/a-loop/#domino-5-view)
+  * [Flows](/doc/03-flows.md) (alpha)
 
 ## Documentation
 
@@ -63,6 +64,7 @@ Then, add the `re-dash` dependency
 - `samples/signals` Same as 'samples/counter' but showing various subscription signals: single, vector & map
 - `samples/coeffects` Shows an example of injecting coeffects into an event handler
 - `samples/local_storage` Shows an example of how to initialize shared_preferences and inject values into event handlers using coeffects
+- `samples/flow` (alpha) Shows an example of using [Flows](/doc/03-flows.md) to calculate a derived result of some calculation, in addition to Flow life-cycle controls.
 
 ## Quickstart
 

bb.edn

@@ -1,16 +1,19 @@
 {:paths ["script"]
- :deps {}
+ :deps  {}
  :tasks
- {compile-tests {:doc "Compile tests"
-                 :task (shell (str "clojure -M:cljd:test compile "
-                                   "hti.re-dash-test"))}
+ {compile-tests {:doc      "Compile tests"
+                 :requires ([clojure.string :as s])
+                 :task (shell (s/join " "
+                                      ["clojure -M:cljd:test compile"
+                                       "hti.re-dash-test"
+                                       "hti.flows-test"]))}
 
-  test          {:doc "Run tests"
-                 :task (shell "flutter test")
-                 :depends [compile-tests]}
-  build         {:doc "Build the jar"
-                 :task (shell "clojure -T:build ci")
-                 :depends []}
-  deploy        {:doc "Deploy to clojars"
-                 :task (shell "clojure -T:build deploy")
-                 :depends []}}}
+  test   {:doc     "Run tests"
+          :task    (shell "flutter test")
+          :depends [compile-tests]}
+  build  {:doc     "Build the jar"
+          :task    (shell "clojure -T:build ci")
+          :depends []}
+  deploy {:doc     "Deploy to clojars"
+          :task    (shell "clojure -T:build deploy")
+          :depends []}}}

deps.edn

@@ -1,7 +1,7 @@
 {:paths ["src"]
  :deps {tensegritics/clojuredart
         {:git/url "https://github.com/tensegritics/ClojureDart.git"
-         :sha "1ba3d2240b3bc5c104620be6d3f723db77dfed68"}}
+         :sha "303e2621391abaf52a7179efb848bf6d73ebb2e8"}}
  :aliases
  {:test
   {:extra-paths ["test"]

doc/03-flows.md

@@ -0,0 +1,41 @@
+# Flows
+
+Status: (alpha)
+
+Flows provide a newer mechanism for derived state, by storing the derived result of some calculation in the app-db at the location you specify.
+
+Flows also manage their own life-cycle ensuring it cleans up after itself when the Flow is no longer needed.
+
+For detailed information see [re-frame's Flow](https://day8.github.io/re-frame/Flows/) documentation.
+
+### Getting started
+
+Register the built-in Flow life-cycle effects in your app's `main` function:
+
+```clojure
+
+(require '[hti.re-dash.alpha :as rd]')  ;; <== Flows are available in the alpha namespace
+
+(rd/register-defaults!)
+```
+
+Register a Flow
+
+```clojure
+
+(def area-flow
+  {:id          :garage-area
+   :inputs      {:w [:garage :width]
+                 :h [:garage :length]}
+   :output      (fn calc-area
+                  [{:keys [w h]}]
+                  (* w h))
+   :path        [:garage :area]})
+
+
+(rd/reg-flow area-flow)
+```
+
+### Sample app
+
+`samples/flow` Shows an example of using Flows to calculate a derived result of some calculation, in addition to Flow life-cycle controls.

samples/coeffects/deps.edn

@@ -1,8 +1,15 @@
-{:paths ["src"]
+{:paths ["src" "../../src"]
  :deps {tensegritics/clojuredart
         {:git/url "https://github.com/tensegritics/ClojureDart.git"
-         :sha "1ba3d2240b3bc5c104620be6d3f723db77dfed68"}
-        net.clojars.htihospitality/re-dash {:mvn/version "0.8.1"}}
+
+         ;; In real use scenario, get the latest SHA from ClojureDart Github page
+         :sha "303e2621391abaf52a7179efb848bf6d73ebb2e8"}
+
+        ;; In real use scenario, remove second, relative source path from :paths above,
+        ;; un-comment the line below, and set to the latest released re-dash version.
+        ;; net.clojars.htihospitality/re-dash {:mvn/version "x.x.x"}
+        }
+
  :aliases {:cljd {:main-opts ["-m" "cljd.build"]}}
  :cljd/opts {:kind :flutter
              :main acme.main}}

samples/coeffects/src/acme/model.cljd

@@ -1,5 +1,5 @@
 (ns acme.model
-  (:require [hti.re-dash :as rd]))
+  (:require [hti.re-dash.core :as rd]))
 
 (defn register!
   []

samples/coeffects/src/acme/view.cljd

@@ -2,7 +2,7 @@
   (:require ["package:flutter/material.dart" :as m]
             [cljd.flutter :as f]
             [acme.model :as model]
-            [hti.re-dash :as rd]))
+            [hti.re-dash.core :as rd]))
 
 (def tomorrow
   (m/Column

samples/counter/deps.edn

@@ -1,8 +1,15 @@
-{:paths ["src"]
+{:paths ["src" "../../src"]
  :deps {tensegritics/clojuredart
         {:git/url "https://github.com/tensegritics/ClojureDart.git"
-         :sha "1ba3d2240b3bc5c104620be6d3f723db77dfed68"}
-        net.clojars.htihospitality/re-dash {:mvn/version "0.8.1"}}
+
+         ;; In real use scenario, get the latest SHA from ClojureDart Github page
+         :sha "303e2621391abaf52a7179efb848bf6d73ebb2e8"}
+
+        ;; In real use scenario, remove second, relative source path from :paths above,
+        ;; un-comment the line below, and set to the latest released re-dash version.
+        ;; net.clojars.htihospitality/re-dash {:mvn/version "x.x.x"}
+        }
+
  :aliases {:cljd {:main-opts ["-m" "cljd.build"]}}
  :cljd/opts {:kind :flutter
              :main acme.main}}

samples/counter/src/acme/model.cljd

@@ -1,5 +1,5 @@
 (ns acme.model
-  (:require [hti.re-dash :as rd]))
+  (:require [hti.re-dash.core :as rd]))
 
 (defn register!
   []

samples/counter/src/acme/view.cljd

@@ -2,7 +2,7 @@
   (:require ["package:flutter/material.dart" :as m]
             [cljd.flutter :as f]
             [acme.model :as model]
-            [hti.re-dash :as rd]))
+            [hti.re-dash.core :as rd]))
 
 (def counter
   (m/Column

samples/event_queue/deps.edn

@@ -1,8 +1,15 @@
-{:paths ["src"]
+{:paths ["src" "../../src"]
  :deps {tensegritics/clojuredart
         {:git/url "https://github.com/tensegritics/ClojureDart.git"
-         :sha "1ba3d2240b3bc5c104620be6d3f723db77dfed68"}
-        net.clojars.htihospitality/re-dash {:mvn/version "0.8.1"}}
+
+         ;; In real use scenario, get the latest SHA from ClojureDart Github page
+         :sha "303e2621391abaf52a7179efb848bf6d73ebb2e8"}
+
+        ;; In real use scenario, remove second, relative source path from :paths above,
+        ;; un-comment the line below, and set to the latest released re-dash version.
+        ;; net.clojars.htihospitality/re-dash {:mvn/version "x.x.x"}
+        }
+
  :aliases {:cljd {:main-opts ["-m" "cljd.build"]}}
  :cljd/opts {:kind :flutter
              :main acme.main}}

samples/event_queue/src/acme/model.cljd

@@ -1,5 +1,5 @@
 (ns acme.model
-  (:require [hti.re-dash :as rd]))
+  (:require [hti.re-dash.core :as rd]))
 
 (defn do-something-for-while
   []
@@ -32,4 +32,4 @@
    ::log-count
    (fn [current-count]
      (do-something-for-while)
-     (println (str "The current-count is " current-count)))))
+     (dart:core/print (str "The current-count is " current-count)))))

samples/event_queue/src/acme/view.cljd

@@ -2,7 +2,7 @@
   (:require ["package:flutter/material.dart" :as m]
             [cljd.flutter :as f]
             [acme.model :as model]
-            [hti.re-dash :as rd]))
+            [hti.re-dash.core :as rd]))
 
 (def counter
   (m/Column

samples/fetch/deps.edn

@@ -1,8 +1,15 @@
-{:paths ["src"] ; where your cljd files are
+{:paths ["src" "../../src"]
  :deps {tensegritics/clojuredart
         {:git/url "https://github.com/tensegritics/ClojureDart.git"
-         :sha "1ba3d2240b3bc5c104620be6d3f723db77dfed68"}
-        net.clojars.htihospitality/re-dash {:mvn/version "0.8.1"}}
+
+         ;; In real use scenario, get the latest SHA from ClojureDart Github page
+         :sha "303e2621391abaf52a7179efb848bf6d73ebb2e8"}
+
+        ;; In real use scenario, remove second, relative source path from :paths above,
+        ;; un-comment the line below, and set to the latest released re-dash version.
+        ;; net.clojars.htihospitality/re-dash {:mvn/version "x.x.x"}
+        }
+
  :aliases {:cljd {:main-opts ["-m" "cljd.build"]}}
  :cljd/opts {:kind :flutter
              :main acme.main}}

samples/fetch/src/acme/model.cljd

@@ -1,6 +1,6 @@
 (ns acme.model
   (:require ["package:http/http.dart" :as http]
-            [hti.re-dash :as rd]))
+            [hti.re-dash.core :as rd]))
 
 (def albums-url (Uri/parse "https://jsonplaceholder.typicode.com/albums/1"))
 

samples/fetch/src/acme/view.cljd

@@ -2,7 +2,7 @@
   (:require ["package:flutter/material.dart" :as m]
             [cljd.flutter :as f]
             [acme.model :as model]
-            [hti.re-dash :as rd]))
+            [hti.re-dash.core :as rd]))
 
 (def albums
   (f/widget

samples/flow/.gitignore

@@ -0,0 +1,44 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.buildlog/
+.history
+.svn/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+# Flutter/Dart/Pub related
+**/doc/api/
+**/ios/Flutter/.last_build_id
+.dart_tool/
+.flutter-plugins
+.flutter-plugins-dependencies
+.packages
+.pub-cache/
+.pub/
+/build/
+
+# Symbolication related
+app.*.symbols
+
+# Obfuscation related
+app.*.map.json
+
+# Android Studio will place build artifacts here
+/android/app/debug
+/android/app/profile
+/android/app/release

samples/flow/.metadata

@@ -0,0 +1,45 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: "d211f42860350d914a5ad8102f9ec32764dc6d06"
+  channel: "stable"
+
+project_type: app
+
+# Tracks metadata for the flutter migrate command
+migration:
+  platforms:
+    - platform: root
+      create_revision: d211f42860350d914a5ad8102f9ec32764dc6d06
+      base_revision: d211f42860350d914a5ad8102f9ec32764dc6d06
+    - platform: android
+      create_revision: d211f42860350d914a5ad8102f9ec32764dc6d06
+      base_revision: d211f42860350d914a5ad8102f9ec32764dc6d06
+    - platform: ios
+      create_revision: d211f42860350d914a5ad8102f9ec32764dc6d06
+      base_revision: d211f42860350d914a5ad8102f9ec32764dc6d06
+    - platform: linux
+      create_revision: d211f42860350d914a5ad8102f9ec32764dc6d06
+      base_revision: d211f42860350d914a5ad8102f9ec32764dc6d06
+    - platform: macos
+      create_revision: d211f42860350d914a5ad8102f9ec32764dc6d06
+      base_revision: d211f42860350d914a5ad8102f9ec32764dc6d06
+    - platform: web
+      create_revision: d211f42860350d914a5ad8102f9ec32764dc6d06
+      base_revision: d211f42860350d914a5ad8102f9ec32764dc6d06
+    - platform: windows
+      create_revision: d211f42860350d914a5ad8102f9ec32764dc6d06
+      base_revision: d211f42860350d914a5ad8102f9ec32764dc6d06
+
+  # User provided section
+
+  # List of Local paths (relative to this file) that should be
+  # ignored by the migrate tool.
+  #
+  # Files that are not part of the templates will be ignored by default.
+  unmanaged_files:
+    - 'lib/main.dart'
+    - 'ios/Runner.xcodeproj/project.pbxproj'

samples/flow/README.md

@@ -0,0 +1,17 @@
+# flow
+
+Shows an example of a Flow's life-cycle, and subscribing to its derived result
+
+## Run the sample
+
+Create the platform folders
+
+```bash
+flutter create .
+```
+
+Run it
+
+```bash
+clj -M:cljd flutter
+```

samples/flow/deps.edn

@@ -0,0 +1,15 @@
+{:paths ["src" "../../src"]
+ :deps {tensegritics/clojuredart
+        {:git/url "https://github.com/tensegritics/ClojureDart.git"
+
+         ;; In real use scenario, get the latest SHA from ClojureDart Github page
+         :sha "303e2621391abaf52a7179efb848bf6d73ebb2e8"}
+
+        ;; In real use scenario, remove second, relative source path from :paths above,
+        ;; un-comment the line below, and set to the latest released re-dash version.
+        ;; net.clojars.htihospitality/re-dash {:mvn/version "x.x.x"}
+        }
+
+ :aliases {:cljd {:main-opts ["-m" "cljd.build"]}}
+ :cljd/opts {:kind :flutter
+             :main acme.main}}

samples/flow/lib/main.dart

@@ -0,0 +1 @@
+export "cljd-out/acme/main.dart" show main;