From 3ab43d52b4f6d6e804382a4d8d9efd8ca61d9481 Mon Sep 17 00:00:00 2001 From: Andrew Dolby Date: Fri, 19 Aug 2016 14:47:37 -0400 Subject: [PATCH] Cleanup docs --- docs/EffectfulEvents.md | 9 ++++----- docs/Interceptors.md | 14 +++++++------- docs/coeffects.md | 8 ++++---- 3 files changed, 15 insertions(+), 16 deletions(-) diff --git a/docs/EffectfulEvents.md b/docs/EffectfulEvents.md index bddd1b5..6990ca6 100644 --- a/docs/EffectfulEvents.md +++ b/docs/EffectfulEvents.md @@ -108,7 +108,7 @@ And here's more carnage: ``` Again, this approach will work. But that dirty great big side-effect doesn't come -for free. Its like a muddy monster truck has shown up in our field of white tulips. +for free. It's like a muddy monster truck has shown up in our field of white tulips. ### Bad, Why? @@ -353,10 +353,10 @@ data from arguments. `-db` handlers and `-fx` handlers are conceptually the same. They only differ numerically. -`-db` handlers take ONE coeeffect called `db`, and they return only ONE effect (db again). +`-db` handlers take ONE coeffect called `db`, and they return only ONE effect (db again). Whereas `-fx` handlers take potentially MANY coeffects (a map of them) and they return -potentially MANY effects (a map of them). So, One vs Many. +potentially MANY effects (a map of them). So, One vs Many. Just to be clear, the following two handlers achieve the same thing: ```clj @@ -381,7 +381,7 @@ can. The `-fx` version is more flexible, so it will sometimes have its place. 90% of the time, simple `-db` handlers are the right tool to use. -But about 10% of the time, our handlers need additional inputs (coeffecs) or they need to +But about 10% of the time, our handlers need additional inputs (coeffects) or they need to cause additional side-effects (effects). That's when you reach for `-fx` handlers. `-fx` handlers allow us to return effects, declaratively in data. @@ -389,4 +389,3 @@ cause additional side-effects (effects). That's when you reach for `-fx` handle In the next tutorial, we'll shine a light on `interceptors` which are the mechanism by which event handlers are executed. That knowledge will give us a springboard to then, as a next step, better understand coeffects and effects. We'll soon be writing our own. - diff --git a/docs/Interceptors.md b/docs/Interceptors.md index 56e6491..4625e77 100644 --- a/docs/Interceptors.md +++ b/docs/Interceptors.md @@ -36,7 +36,7 @@ Flowing" story promoted by re-frame. So, you'll want to use Interceptors because they solve problems, and help you to write nice code. __Second__, under the covers, Interceptors provide the mechanism by which -event handlers are executed (when you `dispatch`). You they are central concept. +event handlers are executed (when you `dispatch`). They are a central concept. ### What Do Interceptors Do? @@ -45,7 +45,7 @@ They wrap. Specifically, they wrap event handlers. Imagine your event handler is like a piece of ham. An interceptor would be -like bread either side of your ham, which makes a sandwich. +like bread on either side of your ham, which makes a sandwich. And two Interceptors, in a chain, would be like you put another pair of bread slices around the outside of the existing sandwich to make @@ -55,7 +55,7 @@ Interceptors wrap on both sides of a handler, layer after layer. ### Wait, I know That Pattern! -Interceptors implement middleware. But differently. +Interceptors implement middleware. But differently. Traditional middleware - often seen in web servers - creates a data processing pipeline via the nested composition of higher order functions. @@ -154,7 +154,7 @@ That's it. That's how an event gets handled. Some data called a `context` is threaded through all the calls. This value is passed as the argument to every `:before` and `:after` -function and they returned it, possibly modified. +function and it is returned by each function, possibly modified. A `context` is a map with this structure: ```clj @@ -189,7 +189,7 @@ DataScript connection. Interceptors can build up `:coeffects`, via their Equally, some interceptors in the chain will have `:after` functions which process the side effects accumulated into `:effects` -including but, not limited to, updates to app-db. +including, but not limited to, updates to app-db. ### Self Modifying @@ -223,7 +223,7 @@ If our components did this: We'd have to write this handler: ```clj -(def-event-db +(reg-event-db :delete-item (fn [db [_ key-to-delete]] ;; <---- Arrgggghhh underscore @@ -239,7 +239,7 @@ What a relief it would be to get rid of it, but how? We'll write an interceptor: Once we have written `trim-event`, our registration will change to look like this: ```clj -(def-event-db +(reg-event-db :delete-item [trim-event] ;; <--- interceptor added (fn diff --git a/docs/coeffects.md b/docs/coeffects.md index 7870f39..142b6e7 100644 --- a/docs/coeffects.md +++ b/docs/coeffects.md @@ -121,7 +121,7 @@ to our event handler (`cofx`). ### `inject-cofx` -`inject-cofx` is part of re-frame API. +`inject-cofx` is part of the re-frame API. It is a function which returns an Interceptor whose `:before` function loads a key/value pair into a `context's` `:coeffect` map. @@ -159,7 +159,7 @@ Each `cofx-id` requires a different action. This function is also part of the re-frame API. -It allows you associate a`cofx-id` (like `:now` or `:local-store`) with a +It allows you to associate a`cofx-id` (like `:now` or `:local-store`) with a handler function that injects the right key/value pair. The function you register will be passed two arguments: @@ -227,7 +227,7 @@ registration functions and have them auto insert the DataScript connection. ### Testing -During testing, you may want to stub out certain coeffets. +During testing, you may want to stub out certain coeffects. You may, for example, want to test that an event handler works using a specific `now`, not a true random number. @@ -240,7 +240,7 @@ In your test, you'd mock out the cofx handler: (assoc coeffects :now (js/Date. 2016 1 1))) ;; now was then ``` -If your test does alter registered coeffect handlers, and you are using `cljs.test`, +If your test does alter registered coeffect handlers, and you are using `cljs.test`, then you can use a `fixture` to restore all coeffects at the end of your test: ```clj (defn re-frame-fixture