19 | * **Clojure/Script interop**: The atom definition is ordinary Clojure code, which works because this is an ordinary `.cljc` file. 20 | 21 | Client/server value transfer 22 | * Only values can be serialized and moved across the network. 23 | * Reference types (e.g. atoms, database connections, Java classes) are unserializable and therefore cannot be moved. 24 | * Quiz: in `(e/server (pr-str (type 1)))`, why do we `pr-str` on the server? Hint: what type is `java.lang.Long`? 25 | * Quiz: in `(e/def x (e/server (e/watch !x)))`, why do we `e/watch` on the server? 26 | 27 | We target full Clojure/Script compatibility 28 | * That means, any valid Clojure expression, when pasted into an Electric body, will evaluate to the same result, and produce the same side effects, in the same order. Electric is additive Clojure, it takes nothing away. 29 | * To achieve this, Electric implements a proper Clojure/Script analyzer to support all Clojure special forms. 30 | * There are minor edge cases (especially as our compiler matures), mostly inconsequential. 31 | * macros work, side effects work, platform interop works, data structures are the same, clojure.core works 32 | * **It's just Clojure!** -------------------------------------------------------------------------------- /src/user/demo_two_clocks.cljc: -------------------------------------------------------------------------------- 1 | (ns user.demo-two-clocks 2 | (:require [hyperfiddle.electric :as e] 3 | [hyperfiddle.electric-dom2 :as dom])) 4 | 5 | (e/defn TwoClocks [] 6 | (e/client 7 | (let [c (e/client e/system-time-ms) 8 | s (e/server e/system-time-ms)] 9 | 10 | (dom/div (dom/text "client time: " c)) 11 | (dom/div (dom/text "server time: " s)) 12 | (dom/div (dom/text "difference: " (- s c)))))) -------------------------------------------------------------------------------- /src/user/demo_two_clocks.md: -------------------------------------------------------------------------------- 1 | What's happening 2 | 3 | * There are two reactive clocks, one on the frontend and one on the server 4 | * When a clock updates, the view incrementally recomputes to stay consistent 5 | * The server clock streams to the client over websocket 6 | * The expression is full-stack – it has frontend parts and backend parts 7 | * The Electric compiler infers the backend/frontend boundary and generates the full-stack app (client and server that coordinate) 8 | * Network sync is automatic and invisible 9 | 10 | Novel forms 11 | 12 | * `e/defn`: defines an Electric function, which is reactive. Electric fns follow all the same rules as ordinary Clojure functions. 13 | * `e/client`, `e/server`: compile time markers, valid in any Electric body 14 | * `e/system-time-ms`: reactive clock, defined with [Missionary](https://github.com/leonoel/missionary) 15 | * `hyperfiddle.electric-dom`: reactive DOM rendering combinators 16 | 17 | Key ideas 18 | 19 | * **multi-tier**: the `TwoClocks` function spans both frontend and backend, which are developed together in a single programming language and compilation unit. See [Multitier programming (wikipedia)](https://en.wikipedia.org/wiki/Multitier_programming) 20 | * **reactive**: the function body is reactive, keeping the DOM in sync with the clocks. Both the frontend and backend parts of the function are reactive. 21 | * **network-transparent**: the network is also reactive. the function transmits data over the network (as implied by the AST) in a way which is invisible to the application programmer. See: [Network transparency (wikipedia)](https://en.wikipedia.org/wiki/Network_transparency) 22 | * **streaming lexical scope**: this is not RPC (request/response), that would be too slow. The server streams `s` without being asked, because it knows the client depends on it. If the client had to request each server clock tick, the timer would pause visibly between each request. 23 | * **dom rendering is free**: Electric is already a general-purpose reactive engine, so electric-dom is nearly trivial, it's just 300 LOC of mostly syntax helpers only. There is neither virtual dom, reconcilier, nor diffing. 24 | 25 | Electric is a reactivity compiler 26 | 27 | * Electric has a DAG-based reactive evaluation model for fine-grained reactivity. 28 | * Electric uses macros to compile actual Clojure syntax into a DAG, using an actual Clojure/Script analyzer. 29 | * Unlike React.js, reactivity is granular to the expression level, not the function level. 30 | * (This is unlike React.js, where reactivity is granular to the function level.) 31 | 32 | Electric code is analyzed at the expression level. 33 | 34 | * `e/defn` defines functions that Electric can analyze the body of 35 | * Each expression, e.g. `(- s c)`, is a node in the DAG. 36 | * Each expression is async 37 | * Each expression is reactive 38 | * Arguments, e.g. `s`, is an edge in the DAG. 39 | * Expressions are recomputed when any argument updates. 40 | 41 | To visualize the DAG, node `(- s c)` has: 42 | * three incoming edges `#{- s c}`, and 43 | * one outgoing edge—the anonymous result—pointing to `(dom/text "skew: " _)`. 44 | * So, if `s` changes, `(- s c)` is recomputed using memoized `c`, and then the `dom/text` reruns (a point write). 45 | 46 | There is an isomorphism between programs and DAGs 47 | 48 | * you already knew this, if you think about it – see [call graph (wikipedia)](https://en.wikipedia.org/wiki/Call_graph) 49 | * The DAG is an abstract representation of a program 50 | * The DAG contains everything there is to know about the flow of data through the Electric program 51 | * Electric uses this DAG to drive reactivity, so we sometimes call the DAG a "reactivity graph". 52 | * But in theory, this DAG is abstract and there could be evaluated (interpreted or compiled) in many ways. 53 | * E.g., in addition to driving reactivity, Electric uses the DAG to drive network topology, which is just a graph coloring problem. 54 | 55 | Network is reactive at the granularity of individual scope values 56 | * when server clock `s` updates, the new value is streamed over network, bound to `s` on the client, ... 57 | * Everything is already async, so adding a 10ms websocket delay does not add impedance, complexity or code weight! 58 | 59 | For a 10min video explainer, see [UIs are streaming DAGs](https://hyperfiddle.notion.site/UIs-are-streaming-DAGs-e181461681a8452bb9c7a9f10f507991). -------------------------------------------------------------------------------- /src/user/demo_virtual_scroll.cljc: -------------------------------------------------------------------------------- 1 | (ns user.demo-virtual-scroll 2 | (:require [contrib.data :refer [unqualify]] 3 | [hyperfiddle.electric :as e] 4 | [hyperfiddle.electric-dom2 :as dom] 5 | [hyperfiddle.electric-ui4 :as ui] 6 | #?(:cljs goog.object))) 7 | 8 | (e/defn DemoFixedHeightCounted 9 | "Scrolls like google sheets. this can efficiently jump through a large indexed collection" 10 | [] 11 | (let [row-count 500 12 | xs (vec (range row-count)) ; counted 13 | page-size 100 14 | row-height 22] ; todo use relative measurement (browser zoom impacts px height) 15 | (e/client 16 | (dom/div (dom/props {:class "viewport" :style {:overflowX "hidden" :overflowY "auto"}}) 17 | (let [[scrollTop] (new (ui/scroll-state< dom/node)) 18 | max-height (* row-count row-height) 19 | clamped-scroll-top (js/Math.min scrollTop max-height) 20 | start (/ clamped-scroll-top row-height)] ; (js/Math.floor) 21 | (dom/div (dom/props {:style {:height (str (* row-height row-count) "px") ; optional absolute scrollbar 22 | :padding-top (str clamped-scroll-top "px") ; seen elements are replaced with padding 23 | :padding-bottom (str (- max-height clamped-scroll-top) "px")}}) 24 | (e/server 25 | ; seen elements are unmounted 26 | (e/for [x #_(subvec xs 27 | (Math/min start row-count) 28 | (Math/min (+ start page-size) row-count)) 29 | (->> xs (drop start) (take page-size))] 30 | (e/client (dom/div (dom/text x))))))))))) 31 | 32 | (e/defn DemoVariableHeightInfinite 33 | "Scrolls like newsfeed. Natural browser layout for variable height rows. Leaves seen elements 34 | mounted in the DOM." 35 | [] 36 | (let [xs (range) ; infinite 37 | page-size 100] 38 | (e/client 39 | (dom/div (dom/props {:class "viewport"}) 40 | (let [!pages (atom 1) pages (e/watch !pages) 41 | [scrollTop scrollHeight clientHeight] (new (ui/scroll-state< dom/node))] 42 | (when (>= scrollTop (- scrollHeight clientHeight clientHeight)) ; scrollThresholdPx = clientHeight 43 | (swap! !pages inc)) ; can this get spammed by Electric? 44 | (dom/div ; content is unstyled, uses natural layout 45 | (e/server 46 | (e/for [x (->> xs (take (* pages page-size)))] ; leave dom 47 | (e/client (dom/div (dom/text x))))))))))) 48 | 49 | #?(:clj (defonce !demo (atom {:text "DemoFixedHeightCounted" ::value `DemoFixedHeightCounted}))) 50 | 51 | (e/def demo (e/server (e/watch !demo))) 52 | 53 | (e/def demos {`DemoVariableHeightInfinite DemoVariableHeightInfinite 54 | `DemoFixedHeightCounted DemoFixedHeightCounted}) 55 | 56 | (e/defn VirtualScroll [] 57 | (e/client 58 | ; Requires css {box-sizing: border-box;} 59 | (dom/element "style" (dom/text ".header { position: fixed; z-index:1; top: 0; left: 0; right: 0; height: 100px; background-color: #abcdef; }" 60 | ".footer { position: fixed; bottom: 0; left: 0; right: 0; height: 100px; background-color: #abcdef; }" 61 | ".viewport { position: fixed; top: 100px; bottom: 100px; left: 0; right: 0; background-color: #F63; overflow: auto; }")) 62 | (dom/div (dom/props {:class "header"}) 63 | (dom/dl 64 | (dom/dt (dom/text "scroll debug state")) 65 | (dom/dd (dom/pre (dom/text (pr-str (update-keys (e/watch ui/!scrollStateDebug) unqualify)))))) 66 | (e/server 67 | (ui/select 68 | demo 69 | (e/fn V! [v] (reset! !demo v)) 70 | (e/fn Options [] [{:text "DemoFixedHeightCounted" ::value `DemoFixedHeightCounted} 71 | {:text "DemoVariableHeightInfinite" ::value `DemoVariableHeightInfinite}]) 72 | (e/fn OptionLabel [x] (:text x))))) 73 | (e/server (new (get demos (::value demo)))) 74 | (dom/div (dom/props {:class "footer"}) 75 | (dom/text "Try scrolling to the top, and resizing the window.")))) 76 | -------------------------------------------------------------------------------- /src/user/demo_webview.cljc: -------------------------------------------------------------------------------- 1 | (ns user.demo-webview 2 | (:require #?(:clj [datascript.core :as d]) 3 | [hyperfiddle.electric :as e] 4 | [hyperfiddle.electric-dom2 :as dom] 5 | [hyperfiddle.electric-ui4 :as ui])) 6 | 7 | #?(:clj 8 | (defonce conn ; state survives reload 9 | (doto (d/create-conn {:order/email {}}) 10 | (d/transact! ; test data 11 | [{:order/email "alice@example.com" :order/gender :order/female} 12 | {:order/email "bob@example.com" :order/gender :order/male} 13 | {:order/email "charlie@example.com" :order/gender :order/male}])))) 14 | 15 | #?(:clj 16 | (defn teeshirt-orders [db ?email] 17 | (sort 18 | (d/q '[:find [?e ...] 19 | :in $ ?needle :where 20 | [?e :order/email ?email] 21 | [(clojure.string/includes? ?email ?needle)]] 22 | db (or ?email ""))))) 23 | 24 | (e/defn Teeshirt-orders-view [db] 25 | (e/client 26 | (dom/div 27 | (let [!search (atom ""), search (e/watch !search)] 28 | (ui/input search (e/fn [v] (reset! !search v)) 29 | (dom/props {:placeholder "Filter..."})) 30 | (dom/table (dom/props {:class "hyperfiddle"}) 31 | (e/server 32 | (e/for [id (teeshirt-orders db search)] 33 | (let [!e (d/entity db id)] 34 | (e/client 35 | (dom/tr 36 | (dom/td (dom/text id)) 37 | (dom/td (dom/text (e/server (:order/email !e)))) 38 | (dom/td (dom/text (e/server (:order/gender !e)))))))))))))) 39 | 40 | (e/defn Webview [] 41 | (e/server 42 | (let [db (e/watch conn)] ; reactive "database value" 43 | (Teeshirt-orders-view. db)))) 44 | 45 | (comment 46 | #?(:clj (d/transact conn [{:db/id 2 :order/email "bob2@example.com"}])) 47 | #?(:clj (d/transact conn [{:order/email "dan@example.com"}])) 48 | #?(:clj (d/transact conn [{:order/email "erin@example.com"}])) 49 | #?(:clj (d/transact conn [{:order/email "frank@example.com"}])) 50 | ) 51 | -------------------------------------------------------------------------------- /src/user/demo_webview.md: -------------------------------------------------------------------------------- 1 | What's happening 2 | * The webview is subscribed to the database, which updates with each transaction. 3 | * If you ran the transact forms at the bottom in your REPL, the view would update reactively. 4 | 5 | Novel forms 6 | * `e/watch` on datascript connection 7 | 8 | Key ideas 9 | * Datascript is on the server, it can be any database 10 | * Direct query/view composition, with a loop -------------------------------------------------------------------------------- /src/user/example_datascript_db.clj: -------------------------------------------------------------------------------- 1 | ;; An example databsae of tee-shirt orders 2 | ;; server side only - for demos 3 | (ns user.example-datascript-db 4 | (:require [datascript.core :as d] 5 | [datascript.impl.entity :as de] ; for `entity?` predicate 6 | [hyperfiddle.api :as hf] 7 | [hyperfiddle.rcf :refer [tests % tap]])) 8 | 9 | (def schema ; user orders a tee-shirt and select a tee-shirt gender and size + optional tags 10 | ;; :hf/valueType is an annotation, used by hyperfiddle to auto render a UI (To be improved. Datascript only accepts :db/valueType on refs) 11 | {:order/email {:hf/valueType :db.type/string, :db/cardinality :db.cardinality/one, :db/unique :db.unique/identity} 12 | :order/gender {:db/valueType :db.type/ref, :db/cardinality :db.cardinality/one} 13 | :order/shirt-size {:db/valueType :db.type/ref, :db/cardinality :db.cardinality/one} 14 | :order/type {:db/cardinality :db.cardinality/one} 15 | :order/tags {:db/cardinality :db.cardinality/many} 16 | :db/ident {:db/unique :db.unique/identity, :hf/valueType :db.type/keyword}}) 17 | 18 | (defn fixtures [db] 19 | (-> db 20 | ;; Add tee-shirt types 21 | (d/with [{:db/id 1, :order/type :order/gender, :db/ident :order/male} ; straight cut 22 | {:db/id 2, :order/type :order/gender, :db/ident :order/female}]) ; fitted 23 | :db-after 24 | ;; Add tee-shirt sizes by type 25 | (d/with [{:db/id 3 :order/type :order/shirt-size :db/ident :order/mens-small :order/gender :order/male} 26 | {:db/id 4 :order/type :order/shirt-size :db/ident :order/mens-medium :order/gender :order/male} 27 | {:db/id 5 :order/type :order/shirt-size :db/ident :order/mens-large :order/gender :order/male} 28 | {:db/id 6 :order/type :order/shirt-size :db/ident :order/womens-small :order/gender :order/female} 29 | {:db/id 7 :order/type :order/shirt-size :db/ident :order/womens-medium :order/gender :order/female} 30 | {:db/id 8 :order/type :order/shirt-size :db/ident :order/womens-large :order/gender :order/female}]) 31 | :db-after 32 | ;; Add example orders 33 | (d/with [{:db/id 9, :order/email "alice@example.com", :order/gender :order/female, :order/shirt-size :order/womens-large, :order/tags [:a :b :c]} 34 | {:db/id 10, :order/email "bob@example.com", :order/gender :order/male, :order/shirt-size :order/mens-large, :order/tags [:b]} 35 | {:db/id 11, :order/email "charlie@example.com", :order/gender :order/male, :order/shirt-size :order/mens-medium}]) 36 | :db-after)) 37 | 38 | (declare conn) 39 | 40 | (defn setup-db! [] 41 | (def conn (d/create-conn schema)) 42 | (alter-var-root #'hf/*$* (constantly (fixtures (d/db conn))))) 43 | 44 | (setup-db!) 45 | 46 | 47 | (def db hf/*$*) ; for @(requiring-resolve 'user.example-datascript-db/db) 48 | 49 | (defn get-schema [db a] (get (:schema db) a)) 50 | 51 | (defn nav! 52 | ([_ e] e) 53 | ([db e a] (let [v (a (if (de/entity? e) e (d/entity db e)))] 54 | (if (de/entity? v) 55 | (or (:db/ident v) (:db/id v)) 56 | v))) 57 | ([db e a & as] (reduce (partial nav! db) (nav! db e a) as))) 58 | 59 | (def male 1 #_:order/male #_17592186045418) 60 | (def female 2 #_:order/female #_17592186045419) 61 | (def m-sm 3 #_17592186045421) 62 | (def m-md 4 #_nil) 63 | (def m-lg 5 #_nil) 64 | (def w-sm 6 #_nil) 65 | (def w-md 7 #_nil) 66 | (def w-lg 8 #_nil) 67 | (def alice 9 #_17592186045428) 68 | (def bob 10 #_nil) 69 | (def charlie 11 #_nil) 70 | 71 | (comment 72 | (hyperfiddle.rcf/enable!)) 73 | 74 | (tests 75 | (def e [:order/email "alice@example.com"]) 76 | 77 | (tests 78 | "(d/pull ['*]) is best for tests" 79 | (d/pull db ['*] e) 80 | := {:db/id 9, 81 | :order/email "alice@example.com", 82 | :order/shirt-size #:db{:id 8}, 83 | :order/gender #:db{:id 2} 84 | :order/tags [:a :b :c]}) 85 | 86 | (comment #_tests 87 | "careful, entity type is not= to equivalent hashmap" 88 | (d/touch (d/entity db e)) 89 | ; expected failure 90 | := {:order/email "alice@example.com", 91 | :order/gender #:db{:id 2}, 92 | :order/shirt-size #:db{:id 8}, 93 | :order/tags #{:c :b :a}, 94 | :db/id 9}) 95 | 96 | (tests 97 | "entities are not maps" 98 | (type (d/touch (d/entity db e))) 99 | *1 := datascript.impl.entity.Entity) ; not a map 100 | 101 | (comment #_tests 102 | "careful, entity API tests are fragile and (into {}) is insufficient" 103 | (->> (d/touch (d/entity db e)) ; touch is the best way to inspect an entity 104 | (into {})) ; but it's hard to convert to a map... 105 | := #:order{#_#_:id 9 ; db/id is not present! 106 | :email "alice@example.com", 107 | :gender _ #_#:db{:id 2}, ; entity ref not =, RCF can’t unify with entities 108 | :shirt-size _ #_#:db{:id 8}, ; entity ref not = 109 | :tags #{:c :b :a}} 110 | 111 | "select keys doesn't fix the problem as it's not recursive" 112 | (-> (d/touch (d/entity db e)) 113 | (select-keys [:order/email :order/shirt-size :order/gender])) 114 | := #:order{:email "alice@example.com", 115 | :shirt-size _ #_#:db{:id 8}, ; still awkward, need recursive pull 116 | :gender _ #_#:db{:id 2}}) ; RCF can’t unify with an entities 117 | 118 | "TLDR is use (d/pull ['*]) like the first example" 119 | (tests 120 | (d/pull db ['*] :order/female) 121 | := {:db/id female :db/ident :order/female :order/type :order/gender}) 122 | 123 | (tests 124 | (d/q '[:find [?e ...] :where [_ :order/gender ?e]] db) 125 | := [2 1] #_[:order/male :order/female]) 126 | ) 127 | -------------------------------------------------------------------------------- /src/user/tutorial_7guis_1_counter.cljc: -------------------------------------------------------------------------------- 1 | (ns user.tutorial-7guis-1-counter 2 | (:require [hyperfiddle.electric :as e] 3 | [hyperfiddle.electric-dom2 :as dom] 4 | [hyperfiddle.electric-ui4 :as ui])) 5 | 6 | (e/defn Counter [] 7 | (e/client 8 | (let [!state (atom 0)] 9 | (dom/p (dom/text (e/watch !state))) 10 | (ui/button (e/fn [] (swap! !state inc)) 11 | (dom/text "Count"))))) -------------------------------------------------------------------------------- /src/user/tutorial_7guis_2_temperature.cljc: -------------------------------------------------------------------------------- 1 | (ns user.tutorial-7guis-2-temperature 2 | (:require clojure.math 3 | [hyperfiddle.electric :as e] 4 | [hyperfiddle.electric-dom2 :as dom] 5 | [hyperfiddle.electric-ui4 :as ui] 6 | [missionary.core :as m])) 7 | 8 | (defn c->f [c] (+ (* c (/ 9 5)) 32)) 9 | (defn f->c [f] (* (- f 32) (/ 5 9))) 10 | (defn random-value [_] (m/sp (m/? (m/sleep 1000)) (rand-int 40))) 11 | 12 | (e/defn TemperatureConverter [] 13 | (e/client 14 | (let [!t (atom 0), t (e/watch !t)] 15 | (reset! !t (new (e/task->cp (random-value t)))) ; test concurrent updates 16 | (dom/dl 17 | (dom/dt (dom/text "Celsius")) 18 | (dom/dd (ui/long (clojure.math/round t) 19 | (e/fn [v] (reset! !t v)))) 20 | (dom/dt (dom/text "Farenheit")) 21 | (dom/dd (ui/long (clojure.math/round (c->f t)) 22 | (e/fn [v] (reset! !t (f->c v))))))))) -------------------------------------------------------------------------------- /src/user/tutorial_7guis_4_timer.cljc: -------------------------------------------------------------------------------- 1 | (ns user.tutorial-7guis-4-timer 2 | (:require [hyperfiddle.electric :as e] 3 | [hyperfiddle.electric-dom2 :as dom] 4 | [hyperfiddle.electric-ui4 :as ui4])) 5 | 6 | (def initial-goal 10) 7 | (defn seconds [milliseconds] (/ (Math/floor (/ milliseconds 100)) 10)) 8 | (defn second-precision [milliseconds] 9 | (-> milliseconds (/ 1000) (Math/floor) (* 1000))) ; drop milliseconds 10 | 11 | (defn now [] #?(:cljs (second-precision (js/Date.now)))) 12 | 13 | (e/defn Timer [] 14 | (e/client 15 | (let [!goal (atom initial-goal) 16 | !start (atom (now)) 17 | goal (e/watch !goal) 18 | goal-ms (* 1000 goal) 19 | start (e/watch !start) 20 | time (min goal-ms (- (second-precision e/system-time-ms) start))] 21 | (dom/div (dom/props {:style {:display :grid ;:margin-left "20rem" 22 | :width "20em" 23 | :grid-gap "0 1rem" 24 | :align-items :center}}) 25 | (dom/span (dom/text "Elapsed Time:")) 26 | (dom/progress (dom/props {:max goal-ms, :value time, :style {:grid-column 2}})) 27 | (dom/span (dom/text (seconds time) " s")) 28 | (dom/span (dom/props {:style {:grid-row 3}}) (dom/text "Duration: " goal "s")) 29 | (ui4/range goal (e/fn [v] (reset! !goal v)) 30 | (dom/props {:min 0, :max 60, :style {:grid-row 3}})) 31 | (ui4/button (e/fn [] (reset! !start (now))) 32 | (dom/props {:style {:grid-row 4, :grid-column "1/3"}}) 33 | (dom/text "Reset")))))) 34 | -------------------------------------------------------------------------------- /src/user/tutorial_7guis_5_crud.cljc: -------------------------------------------------------------------------------- 1 | (ns user.tutorial-7guis-5-crud 2 | (:require [clojure.string :as str] 3 | [hyperfiddle.electric :as e] 4 | [hyperfiddle.electric-dom2 :as dom] 5 | [hyperfiddle.electric-ui4 :as ui4])) 6 | 7 | (def !state (atom {:selected nil 8 | :stage {:name "" 9 | :surname ""} 10 | :names (sorted-map 0 {:name "Emil", :surname "Hans"})})) 11 | 12 | (def next-id (partial swap! (atom 0) inc)) 13 | 14 | (defn select! [id] 15 | (swap! !state (fn [state] 16 | (assoc state :selected id 17 | :stage (get-in state [:names id]))))) 18 | 19 | (defn set-name! [name] 20 | (swap! !state assoc-in [:stage :name] name)) 21 | 22 | (defn set-surname! [surname] 23 | (swap! !state assoc-in [:stage :surname] surname)) 24 | 25 | (defn create! [] 26 | (swap! !state (fn [{:keys [stage] :as state}] 27 | (-> state 28 | (update :names assoc (next-id) stage) 29 | (assoc :stage {:name "", :surname ""}))))) 30 | (defn delete! [] 31 | (swap! !state (fn [{:keys [selected] :as state}] 32 | (update state :names dissoc selected)))) 33 | 34 | (defn update! [] 35 | (swap! !state (fn [{:keys [selected stage] :as state}] 36 | (assoc-in state [:names selected] stage)))) 37 | 38 | (defn filter-names [names-map needle] 39 | (if (empty? needle) 40 | names-map 41 | (let [needle (str/lower-case needle)] 42 | (reduce-kv (fn [r k {:keys [name surname]}] 43 | (if (or (str/includes? (str/lower-case name) needle) 44 | (str/includes? (str/lower-case surname) needle)) 45 | r 46 | (dissoc r k))) 47 | names-map names-map)))) 48 | 49 | (e/defn CRUD [] 50 | (e/client 51 | (let [state (e/watch !state) 52 | selected (:selected state)] 53 | (dom/div (dom/props {:style {:display :grid 54 | :grid-gap "0.5rem" 55 | :align-items :baseline 56 | :grid-template-areas "'a b c c'\n 57 | 'd d e f'\n 58 | 'd d g h'\n 59 | 'd d i i'\n 60 | 'j j j j'"}}) 61 | (dom/span (dom/props {:style {:grid-area "a"}}) 62 | (dom/text "Filter prefix:")) 63 | (let [!needle (atom ""), needle (e/watch !needle)] 64 | (ui4/input needle (e/fn [v] (reset! !needle v)) 65 | (dom/props {:style {:grid-area "b"}})) 66 | (dom/ul (dom/props {:style {:grid-area "d" 67 | :background-color :white 68 | :list-style-type :none 69 | :padding 0 70 | :border "1px gray solid" 71 | :height "100%"}}) 72 | (e/for [entry (filter-names (:names state) needle)] 73 | (let [id (key entry) 74 | value (val entry)] 75 | (dom/li (dom/text (:surname value) ", " (:name value)) 76 | (dom/props 77 | {:style {:cursor :pointer 78 | :color (if (= selected id) :white :inherit) 79 | :background-color (if (= selected id) :blue :inherit) 80 | :padding "0.1rem 0.5rem"}}) 81 | (dom/on "click" (e/fn [_] (select! id)))))))) 82 | (let [stage (:stage state)] 83 | (dom/span (dom/props {:style {:grid-area "e"}}) (dom/text "Name:")) 84 | (ui4/input (:name stage) (e/fn [v] (set-name! v)) 85 | (dom/props {:style {:grid-area "f"}})) 86 | (dom/span (dom/props {:style {:grid-area "g"}}) (dom/text "Surname:")) 87 | (ui4/input (:surname stage) (e/fn [v] (set-surname! v)) 88 | (dom/props {:style {:grid-area "h"}}))) 89 | (dom/div (dom/props 90 | {:style {:grid-area "j" 91 | :display :grid 92 | :grid-gap "0.5rem" 93 | :grid-template-columns "auto auto auto 1fr"}}) 94 | (ui4/button (e/fn [] (create!)) (dom/text "Create")) 95 | (ui4/button (e/fn [] (update!)) (dom/text "Update") 96 | (dom/props {:disabled (not selected)})) 97 | (ui4/button (e/fn [] (delete!)) (dom/text "Delete") 98 | (dom/props {:disabled (not selected)}))))))) 99 | -------------------------------------------------------------------------------- /src/user/tutorial_backpressure.cljc: -------------------------------------------------------------------------------- 1 | (ns user.tutorial-backpressure 2 | (:require [hyperfiddle.electric :as e] 3 | [hyperfiddle.electric-dom2 :as dom])) 4 | 5 | (e/defn Backpressure [] 6 | (e/client 7 | (let [c (e/client e/system-time-secs) 8 | s (e/server (double e/system-time-secs))] 9 | 10 | (println "s" (int s)) 11 | (println "c" (int c)) 12 | 13 | (dom/div (dom/text "client time: " c)) 14 | (dom/div (dom/text "server time: " s)) 15 | (dom/div (dom/text "difference: " (.toPrecision (- s c) 2)))))) -------------------------------------------------------------------------------- /src/user/tutorial_backpressure.md: -------------------------------------------------------------------------------- 1 | What's happening 2 | * The timer `e/system-time-secs` is a float and updates at the browser animation rate, let's say 120hz. 3 | * Clocks are printed to both the DOM (at 120hz) and also the browser console (at 1hz) 4 | * The clocks pause when the browser page is not visible (i.e. you switch tabs), confirm it 5 | 6 | Novel forms 7 | * None 8 | 9 | Key ideas 10 | * **work-skipping**: expressions are only recomputed if an argument actually changes, otherwise the previous value is reused. Here, the truncated clock timer does not needlessly spam the println; downstream nodes are only recomputed on the transition. 11 | * **signals**: Electric reactive functions model *signals*, not *streams*. Streams are like mouse clicks or database transactions – you can't skip one. Signals are like mouse coordinates, audio signals or game animations – you mostly only care about latest, nobody wants an animation frame from 2 seconds ago. 12 | * **the reactive clocks are lazy**: the clocks do not tick until the previous tick was *sampled* (i.e. consumed). That means if the rendering process falls behind the requestAnimationFrame tick rate, it will simply skip frames like a video game. 13 | * **lazy sampling**: All electric expressions are lazily sampled, not just the clocks. Electric fns don't compute anything at all until sampled by the Electric entrypoint. 14 | 15 | Clock details 16 | * `e/system-time-secs` is implemented as a missionary flow. 17 | * on the client, the underlying clock is implemented with `requestAnimationFrame` such that it only schedules work once the current tick has been sampled. 18 | * That means, if you switch to another tab, the browser will stop scheduling animation frames and the clock will pause. 19 | * The server clock is implemented similarly, it will tick as fast as possible but only when sampled. If nobody is consuming the clock — i.e. no websockets are connected — the clock will not tick at all! 20 | 21 | Work-skipping 22 | * We use `int` to truncate the precision. The truncation is performed at 120hz, as we want to switch *precisely* on the rising edge of the transition. 23 | * Since `int` is recomputing at 120hz, that means anything immediately downstream will be checked 120 times per second 24 | * so both `(println "s" (int s))` and `(- s c)` are both checked at 120hz 25 | * However, expressions only run if at least one argument has changed 26 | * So, at this point the memoization kicks in and we will skip the work, this is called "work-skipping" 27 | * `(println "s" (int s))` prints at 1hz not 120hz 28 | 29 | Lazy sampling 30 | * Q: Truncating at 120hz is inefficient right? Why not use `(js/setTimeout 1000)` to make a slower clock? 31 | * A: Actually, the fast clock is perfectly efficient due to Electric's backpressure. 32 | * If the rendering process can't keep up with the requestAnimationFrame tick rate, it will simply skip frames, and this will actually slow down the clock because the clock itself is lazy too. 33 | * This is a form of backpressure. See [Streams vs Signals](https://www.dustingetz.com/#/page/signals%20vs%20streams%2C%20in%20terms%20of%20backpressure%20%282023%29) 34 | * Note: Computers can do 3D transforms in realtime, running this little clock at the browser animation rate is negligible. 35 | * If your computer is powered on and plugged in, you generally want to animate at the highest framerate the device is capable of. This is Electric's default behavior out of the box. 36 | 37 | Backpressure 38 | * What if you're on an old mobile device that can't keep up with the server clock streaming? 39 | * In this case, incoming messages from server will saturate the websocket buffer, 40 | * then the browser will propagate backpressure at the TCP layer, 41 | * then the server will decrease the *sampling rate*. 42 | * Same behavior in the opposite direction (e.g if the client generates lots of events and the server is overloaded). 43 | * See: [Signals vs Streams, in terms of backpressure](https://www.dustingetz.com/#/page/signals%20vs%20streams%2C%20in%20terms%20of%20backpressure%20%282023%29) 44 | * Electric is a Clojure to [Missionary](https://github.com/leonoel/missionary) compiler; it compiles lifts each Clojure form into a Missionary continuous flow. 45 | * Thereby automatically backpressuring every point in the Electric DAG. 46 | * If you want to customize the backpressure locally at any point — maybe you want to run a chat view with realtime network but run a slow query less aggressively — you can drop down into missionary's rich suite of concurrency combinators. 47 | -------------------------------------------------------------------------------- /src/user/tutorial_lifecycle.cljc: -------------------------------------------------------------------------------- 1 | (ns user.tutorial-lifecycle 2 | (:require [hyperfiddle.electric :as e] 3 | [hyperfiddle.electric-dom2 :as dom])) 4 | 5 | (e/defn BlinkerComponent [] 6 | (e/client 7 | (dom/h1 (dom/text "blink!")) 8 | (println 'component-did-mount) 9 | (e/on-unmount #(println 'component-will-unmount)))) 10 | 11 | (e/defn Lifecycle [] 12 | (e/client 13 | (if (= 0 (int (mod e/system-time-secs 2))) 14 | (BlinkerComponent.)))) 15 | -------------------------------------------------------------------------------- /src/user/tutorial_lifecycle.md: -------------------------------------------------------------------------------- 1 | What's happening 2 | 3 | * The string "blink!" is being mounted/unmounted every 2 seconds 4 | * The mount/unmount "component lifecycle" is logged to the browser console with `println` 5 | * `(BlinkerComponent.)` is being constructed and destructed 6 | 7 | Novel forms 8 | 9 | * `new`: calls an `e/fn` or `e/defn`. Here, `(BlinkerComponent.)` is desugared by Clojure to `(new BlinkerComponent)`, these two forms are identical. 10 | * `e/on-unmount` : takes a regular (non-reactive) function to run before unmount. 11 | * Why no `e/mount`? The `println` here runs on mount without extra syntax needed, we'd like to see a concrete use case not covered by this. 12 | 13 | Key ideas 14 | 15 | * **Electric functions have object lifecycle**: Reactive expressions have a "mount" and "unmount" lifecycle. `println` here runs on "mount" and never again since it has only constant arguments, unless the component is destroyed and recreated. 16 | * **Call Electric fns with `new`**: Reagent has ctor syntax too; in Reagent we call components with square brackets. This syntax distinguishes between calling Electric fns vs ordinary Clojure fns. To help remember, we capitalize Electric functions, same as Reagent/React components. 17 | * **Electric fns are both functions and objects**: They compose as functions, they have object lifecycle, and they have state. From here on we will refer to Electric fns as both "function" or "object" as appropriate, depending on which aspects are under discussion. We also sometimes refer to "calling" Electric fns as "booting" or "mounting". 18 | * **DAG as a value**: Electric lambdas `e/fn` are values, these can be thought of as "higher order DAGs", "DAG values" or "pieces of DAG". 19 | * **process supervision** 20 | 21 | New 22 | 23 | * Electric `new` is backwards compatible with Clojure/Script's new; if you pass it a class it will do the right thing. 24 | * Q: Why do we need syntax to call Electric fns, why not just use metadata on the var? A: Because lambdas. 25 | * Electric expressions can call both Electric lambdas and ordinary Clojure lambdas (like the sharp-lambda passed to e-unmount). 26 | * Due to Clojure being dynamically typed, there's no static information available for the compiler to infer the right call convention in this case. 27 | * That's why Reagent uses `[F]` and Electric uses `(F.)`. Note both capitalize `F`! 28 | 29 | Dynamic extent 30 | 31 | - Electric objects have *dynamic extent*. 32 | - "Dynamic extent refers to things that exist for a fixed period of time and are explicitly “destroyed” at the end of that period, usually when control returns to the code that created the thing." — from [On the Perils of Dynamic Scope (Sierra 2013)](https://stuartsierra.com/2013/03/29/perils-of-dynamic-scope) 33 | - Like [RAII](https://en.wikipedia.org/wiki/Resource_acquisition_is_initialization), this lifecycle is deterministic and intended for performing resource management effects. 34 | 35 | Process supervision 36 | - Electric `if` and other control flow nodes will mount and unmount their child branches (like switching the railroad track). 37 | - If an `e/fn` were to be booted inside of an `if`, the lifetime of the booted lambda is the duration for which the branch of the `if` is active. 38 | - Electric objects can manage references (e.g. DOM node or atom in lexical scope). 39 | - A managed reference's lifetime is tied to the supervising object's lifetime. 40 | 41 | Object state 42 | 43 | - Recall that Electric functions are auto-memoized. This memo buffer can be seen as the *object state*. 44 | - The memo buffer is discarded and reset when this happens. 45 | - In other words: Electric flows are not [*history sensitive*](https://blog.janestreet.com/breaking-down-frp/). (I hesitate to link to this article from 2014 because it contains confusion/FUD around the importance of continuous time, but the coverage of history sensitivity is good.) -------------------------------------------------------------------------------- /src/user_main.cljc: -------------------------------------------------------------------------------- 1 | (ns user-main 2 | (:require clojure.edn 3 | clojure.string 4 | contrib.data 5 | contrib.ednish 6 | contrib.uri ; data_readers 7 | #?(:clj markdown.core) 8 | [contrib.electric-codemirror :refer [CodeMirror]] 9 | [hyperfiddle.electric :as e] 10 | [hyperfiddle.electric-dom2 :as dom] 11 | [hyperfiddle.electric-svg :as svg] 12 | [hyperfiddle.history :as history] 13 | user.demo-index 14 | 15 | user.demo-two-clocks 16 | user.demo-toggle 17 | user.demo-system-properties 18 | user.demo-chat 19 | user.demo-chat-extended 20 | user.demo-webview 21 | user.demo-todomvc 22 | user.demo-todomvc-composed 23 | 24 | user.demo-explorer 25 | #_wip.demo-explorer2 26 | user.demo-10k-dom 27 | user.demo-svg 28 | user.demo-todos-simple 29 | user.tutorial-7guis-1-counter 30 | user.tutorial-7guis-2-temperature 31 | user.tutorial-7guis-4-timer 32 | user.tutorial-7guis-5-crud 33 | user.demo-virtual-scroll 34 | user.demo-color 35 | user.demo-tic-tac-toe 36 | user.tutorial-lifecycle 37 | user.tutorial-backpressure 38 | #_wip.demo-branched-route 39 | #_wip.hfql 40 | wip.tag-picker 41 | #_wip.teeshirt-orders ; sensitive to electric dep, HFQL moved 42 | wip.demo-custom-types 43 | wip.tracing 44 | user.demo-reagent-interop ; yarn 45 | wip.demo-stage-ui4 ; yarn 46 | wip.js-interop)) 47 | 48 | (e/defn NotFoundPage [] 49 | (e/client (dom/h1 (dom/text "Page not found")))) 50 | 51 | ; todo: macro to auto-install demos by attaching clj metadata to e/defn vars? 52 | 53 | (e/def pages 54 | {`user.demo-two-clocks/TwoClocks user.demo-two-clocks/TwoClocks 55 | `user.demo-toggle/Toggle user.demo-toggle/Toggle 56 | `user.demo-system-properties/SystemProperties user.demo-system-properties/SystemProperties 57 | `user.demo-chat/Chat user.demo-chat/Chat 58 | `user.tutorial-backpressure/Backpressure user.tutorial-backpressure/Backpressure 59 | `user.tutorial-lifecycle/Lifecycle user.tutorial-lifecycle/Lifecycle 60 | `user.demo-chat-extended/ChatExtended user.demo-chat-extended/ChatExtended 61 | `user.demo-webview/Webview user.demo-webview/Webview 62 | `user.demo-todos-simple/TodoList user.demo-todos-simple/TodoList 63 | `user.demo-reagent-interop/ReagentInterop user.demo-reagent-interop/ReagentInterop 64 | ;; `wip.demo-stage-ui4/CrudForm wip.demo-stage-ui4/CrudForm 65 | `user.demo-svg/SVG user.demo-svg/SVG 66 | ; -- `wip.tracing/TracingDemo wip.tracing/TracingDemo 67 | `wip.demo-custom-types/CustomTypes wip.demo-custom-types/CustomTypes 68 | 69 | ; 7 GUIs 70 | `user.tutorial-7guis-1-counter/Counter user.tutorial-7guis-1-counter/Counter 71 | `user.tutorial-7guis-2-temperature/TemperatureConverter user.tutorial-7guis-2-temperature/TemperatureConverter 72 | `user.tutorial-7guis-4-timer/Timer user.tutorial-7guis-4-timer/Timer 73 | `user.tutorial-7guis-5-crud/CRUD user.tutorial-7guis-5-crud/CRUD 74 | 75 | ; Demos 76 | ;; `user.demo-todomvc/TodoMVC user.demo-todomvc/TodoMVC 77 | ;; `user.demo-todomvc-composed/TodoMVC-composed user.demo-todomvc-composed/TodoMVC-composed 78 | ;; `user.demo-explorer/DirectoryExplorer user.demo-explorer/DirectoryExplorer 79 | ;-- `wip.datomic-browser/DatomicBrowser wip.datomic-browser/DatomicBrowser -- separate repo now, should it come back? 80 | ; `user.demo-color/Color user.demo-color/Color 81 | ; -- user.demo-10k-dom/Dom-10k-Elements user.demo-10k-dom/Dom-10k-Elements ; todo too slow to unmount, crashes 82 | 83 | ; Hyperfiddle demos 84 | ;`wip.teeshirt-orders/Webview-HFQL wip.teeshirt-orders/Webview-HFQL 85 | ; `wip.demo-branched-route/RecursiveRouter wip.demo-branched-route/RecursiveRouter 86 | ; `wip.demo-explorer2/DirectoryExplorer-HFQL wip.demo-explorer2/DirectoryExplorer-HFQL 87 | 88 | ; Hyperfiddle tutorials 89 | ; `wip.tag-picker/TagPicker wip.tag-picker/TagPicker 90 | 91 | ; Triage 92 | ; `user.demo-virtual-scroll/VirtualScroll user.demo-virtual-scroll/VirtualScroll 93 | ; `user.demo-tic-tac-toe/TicTacToe user.demo-tic-tac-toe/TicTacToe 94 | 95 | ; Tests 96 | ; ::demos/dennis-exception-leak wip.dennis-exception-leak/App2 97 | 98 | ;`wip.js-interop/QRCode wip.js-interop/QRCode 99 | }) 100 | 101 | #?(:clj (defn resolve-var-or-ns [sym] 102 | (if (qualified-symbol? sym) 103 | (ns-resolve *ns* sym) 104 | (the-ns sym)))) 105 | 106 | #?(:clj (defn get-src [sym] 107 | (try (-> (resolve-var-or-ns sym) meta :file 108 | (->> (str "src/")) slurp) 109 | (catch java.io.FileNotFoundException _)))) 110 | 111 | #?(:clj (defn get-readme [sym] 112 | (try (-> (resolve-var-or-ns sym) meta :file 113 | (clojure.string/split #"\.(clj|cljs|cljc)") first (str ".md") 114 | (->> (str "src/")) slurp) 115 | (catch java.io.FileNotFoundException _)))) 116 | 117 | (comment 118 | (get-src `user.demo-two-clocks/TwoClocks) 119 | (get-src 'user) 120 | (get-readme 'user) 121 | (-> (resolve-var-or-ns 'user) meta :file) 122 | (get-readme `user.demo-two-clocks/TwoClocks)) 123 | 124 | (e/defn Code [page] 125 | (e/client 126 | (dom/fieldset 127 | (dom/props {:class "user-examples-code"}) 128 | (dom/legend (dom/text "Code")) 129 | #_(dom/pre (dom/text (e/server (get-src page)))) 130 | (CodeMirror. {:parent dom/node :readonly true} identity identity (e/server (get-src page)))))) 131 | 132 | (e/defn App [page] 133 | (e/client 134 | (dom/fieldset 135 | (dom/props {:class ["user-examples-target" (some-> page name)]}) 136 | (dom/legend (dom/text "Result")) 137 | (e/server (new (get pages page NotFoundPage)))))) 138 | 139 | (e/defn Markdown [?md-str] 140 | (e/client 141 | (let [html (e/server (some-> ?md-str markdown.core/md-to-html-string))] 142 | (set! (.-innerHTML dom/node) html)))) 143 | 144 | (e/defn Readme [page] 145 | (e/client 146 | (dom/div 147 | (dom/props {:class "user-examples-readme markdown-body"}) 148 | (e/server (Markdown. (get-readme page)))))) 149 | 150 | (def tutorials 151 | [["Electric" 152 | [{::id `user.demo-two-clocks/TwoClocks 153 | ::title "Two Clocks – Hello World" 154 | ::lead "Streaming lexical scope. The server clock is streamed to the client."} 155 | {::id `user.demo-toggle/Toggle 156 | ::lead "This demo toggles between client and server with a button."} 157 | {::id `user.demo-system-properties/SystemProperties 158 | ::lead "A larger example of a HTML table backed by a server-side query. Type into the input and see the query update live."} 159 | {::id `user.demo-chat/Chat ::lead "A multiplayer chat app in 30 LOC, all one file. Try two tabs."} 160 | {::id `user.tutorial-backpressure/Backpressure ::lead "This is just the Two Clocks demo with slight modifications, there is more to learn here."} 161 | {::id `user.tutorial-lifecycle/Lifecycle ::title "Component Lifecycle" ::lead "mount/unmount component lifecycle"} 162 | #_{::id 'user ::title "Electric Entrypoint" ::suppress-demo true 163 | ::lead "This is the Electric entrypoint (in user.cljs). `hyperfiddle.electric/boot` is the Electric compiler entrypoint."} 164 | {::id `user.demo-chat-extended/ChatExtended 165 | ::lead "Extended chat demo with auth and presence. When multiple sessions are connected, you can see who else is present."} 166 | {::id `user.demo-webview/Webview 167 | ::lead "A database backed webview with reactive updates."} 168 | {::id `user.demo-todos-simple/TodoList 169 | ::lead "minimal todo list. it's multiplayer, try two tabs"} 170 | {::id `user.demo-reagent-interop/ReagentInterop 171 | ::lead "Reagent (React.js) embedded inside Electric. The reactive mouse coordinates cross from Electric to Reagent via props."} 172 | {::id `user.demo-svg/SVG 173 | ::lead "SVG support. Note the animation is reactive and driven by javascript cosine."} 174 | 175 | ; 7 GUIs 176 | {::id `user.tutorial-7guis-1-counter/Counter ::title "7GUIs Counter" 177 | ::lead "See