From bb765dd1b81aa7a00a939164731ccbbe4cb6e747 Mon Sep 17 00:00:00 2001 From: Matthew Jaoudi Date: Fri, 16 Dec 2016 22:28:26 -0800 Subject: [PATCH 1/3] fix typos in mental model omnibus; --- docs/MentalModelOmnibus.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/MentalModelOmnibus.md b/docs/MentalModelOmnibus.md index 03add17..af0b793 100644 --- a/docs/MentalModelOmnibus.md +++ b/docs/MentalModelOmnibus.md @@ -13,7 +13,7 @@ then those patterns will repeat themselves.
The re-frame tutorials initially focus on the **domino narrative**. The goal is to efficiently explain the mechanics of re-frame, -and get you reading and writing code ASAP. +and to get you reading and writing code ASAP. But **there are other perspectives** on re-frame which will deepen your understanding. @@ -42,7 +42,7 @@ at least one "Aaaah, I see" moment before the end. ## What is the problem? First, we decided to build our SPA apps with ClojureScript, then we -choose [Reagent], then we had a problem. It was mid 2014. +chose [Reagent], then we had a problem. It was mid 2014. For all its considerable brilliance, Reagent (+ React) delivers only the 'V' part of a traditional MVC framework. @@ -52,7 +52,7 @@ SPAs which can run to 50K lines of code. So, I wanted to know: where does the control logic go? How is state stored & manipulated? etc. We read up on [Pedestal App], [Flux], -[Hoplon], [Om], early [Elm], etc and re-frame is the architecture that +[Hoplon], [Om], early [Elm], etc., and re-frame is the architecture that emerged. Since then, we've tried to keep an eye on further developments like the Elm Architecture, Om.Next, BEST, Cycle.js, Redux, etc. They have taught us much although we have often made different choices. @@ -72,8 +72,8 @@ insider's joke, conference T-Shirt. ## Guiding Philosophy -__First__, above all we believe in the one true [Dan Holmsand], creator of Reagent, and -his divine instrument the `ratom`. We genuflect towards Sweden once a day. +__First__, above all, we believe in the one true [Dan Holmsand], creator of Reagent, and +his divine instrument: the `ratom`. We genuflect towards Sweden once a day. __Second__, we believe in ClojureScript, immutable data and the process of building a system out of pure functions. @@ -117,7 +117,7 @@ If you have that data, then you can reproduce the error. re-frame allows you to time travel, even in a production setting. Install the "checkpoint" state into `app-db` -and then "play forward" through the collection dispatched events. +and then "play forward" through the collection of dispatched events. The only way the app "moves forwards" is via events. "Replaying events" moves you step by step towards the error causing problem. @@ -164,9 +164,9 @@ imagined `perpetual reduce` stores its on-going reduction. Now, in the general case, this perspective breaks down a bit, because of `reg-event-fx` (has `-fx` on the end, not `-db`) which allows: - 1. event handlers can produce `effects` beyond just application state + 1. Event handlers to produce `effects` beyond just application state changes. - 2. Event handlers sometimes need coeffects (arguments) in addition to `db` and `v`. + 2. Event handlers to have `coeffects` (arguments) in addition to `db` and `v`. But, even if it isn't the full picture, it is a very useful and interesting mental model. We were first exposed to this idea @@ -201,10 +201,10 @@ This is an infinite loop of sorts - an infinite loop of derived data. `event handlers` collectively implement the "control" part of an application. Their logic interprets arriving events in the context of existing state, -and they compute what the new state of the application. +and they compute the new state of the application. -`events` act, then, a bit like the `triggers` in a finite state machine, and -the event handlers act like the rules which govern how the state machine +`events` act a bit like the `triggers` in a finite state machine, and +the `event handlers` act like the rules which govern how the state machine moves from one logical state to the next. In the simplest @@ -218,7 +218,7 @@ one of them, then formally recognising it and using a technique like [State Charts](https://www.amazon.com/Constructing-User-Interface-Statecharts-Horrocks/dp/0201342782) will help greatly in getting a clean design and fewer bugs. -The beauty of re-frame from a FSM point of view is that all the state is +The beauty of re-frame, from a FSM point of view, is that all the state is in one place - unlike OO systems where the state is distributed (and synchronized) across many objects. So implementing your control logic as a FSM is fairly natural in re-frame, whereas it is often difficult and From 609299ca7141d73f958cc98b4a36090b6aac9dcb Mon Sep 17 00:00:00 2001 From: Matthew Jaoudi Date: Fri, 16 Dec 2016 22:58:49 -0800 Subject: [PATCH 2/3] fix typos in effectful handlers; --- docs/EffectfulHandlers.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/EffectfulHandlers.md b/docs/EffectfulHandlers.md index 4aed939..7d246c5 100644 --- a/docs/EffectfulHandlers.md +++ b/docs/EffectfulHandlers.md @@ -53,7 +53,7 @@ websocket message. Without mutation, an app would just sit there, stuck. State change is how an application "moves forward" - how it does its job. Useful! On the other hand, control logic and state mutation tend to be the most -complex and error prone of part of an app. +complex and error prone part of an app. ### Your Handling @@ -131,7 +131,7 @@ Regarding the 3rd point above, a re-frame application proceeds step by step, lik Such a collection of events is replay-able which is a dream for debugging and testing. But only when all the handlers are pure. Handlers with side-effects (like that HTTP GET, or the `dispatch`) pollute the -replay, inserting extra events into it, etc, which ruins the process. +replay, inserting extra events into it, etc., which ruins the process. ### The 2nd Kind Of Problem @@ -176,7 +176,7 @@ which *do side-effects*, we'll instead get them to *cause side-effects*. ### Doing vs Causing -Above, I proudly claimed that this event handler was pure: +I proudly claim that this event handler is pure: ```clj (reg-event-db :my-event @@ -259,7 +259,7 @@ Here it is re-written so as to be pure: Notes:
*<1>* we're using `reg-event-fx` instead of `reg-event-db` to register (that's `-db` vs `-fx`)
*<2>* the first parameter is no longer just `db`. It is a map from which -[we are destructuring db](http://clojure.org/guides/destructuring). Ie. +[we are destructuring db](http://clojure.org/guides/destructuring), i.e. it is a map which contains a `:db` key.
*<3>* The handler is returning a data structure (map) which describes two side-effects: - a change to application state, via the `:db` key From 3442726a54771bf57df73ed4cfe6578770009312 Mon Sep 17 00:00:00 2001 From: Matthew Jaoudi Date: Fri, 16 Dec 2016 23:25:46 -0800 Subject: [PATCH 3/3] fix typos in re-frame interceptors; --- docs/Interceptors.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/Interceptors.md b/docs/Interceptors.md index fa5b6b7..ce51884 100644 --- a/docs/Interceptors.md +++ b/docs/Interceptors.md @@ -296,7 +296,7 @@ Earlier, in the "Handlers Are Interceptors Too" section, I explained that `event are wrapped in an Interceptor and placed on the end of an Interceptor chain. Remember the whole `[std1 std2 in1 in2 h]` thing? -We're now look at the `h` bit. How does an event handler get wrapped to be an Interceptor. +We'll now look at the `h` bit. How does an event handler get wrapped to be an Interceptor? Reminder - there's two kinds of handler: - the `-db` variety registered by `reg-event-db` @@ -367,9 +367,9 @@ In the next Tutorial, we'll look at (side) Effects in more depth. Later again, ## Appendix -### The Builtin Interceptors +### The Built-in Interceptors -re-frame comes with some builtin Interceptors: +re-frame comes with some built-in Interceptors: - __debug__: log each event as it is processed. Shows incremental [`clojure.data/diff`](https://clojuredocs.org/clojure.data/diff) reports. - __trim-v__: a convenience. More readable handlers.