diff --git a/CHANGES.md b/CHANGES.md index 95bbd2e..4f057ba 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,28 +1,28 @@ -## Unreleased +## Unreleased 0.10.0 (2017.07.NN) -#### New +#### New Docs - - added [an API document](/docs/API.md) + - added [API documentation](/docs/API.md) - added [testing docs](/docs/Testing.md) - added [a new mental model](/docs/MentalModelOmnibus.md#on-dsls-and-machines) - added [a new FAQ entry](docs/FAQs/When-Does-Dispatch-Happen.md) on dispatch processing - - The effect handler for `:dispatch-n` will now ignore `nils`. [See checkin](https://github.com/Day8/re-frame/commit/6efdae438f393f8121a2d6dfbf76db00e6dafbf5) -#### Breaking +#### Breaking - [#357](https://github.com/Day8/re-frame/pull/357) I'd be amazed if this actually broke any apps. Shocked! But, better safe than sorry. - The effect handler for `:db` has changed: if the value provided tests + The effect handler for `:db` has changed: if the new value provided tests `identical?` to the existing value within `app-db`, then `app-db` is not `reset!`. - Previously, `app-db` was always `reset!` when a `:db` effect was supplied, - which caused Layer 2 subscriptions to run unnecessarily. So this is a tiny - efficiency change in an edge case, which also results in behaviour that better matches + Previously, `app-db` was always `reset!` irrespective, + which potentially caused Layer 2 subscriptions to run unnecessarily. So this is a tiny + efficiency change in this edge case, and it results in behaviour that better matches programmer intuitions. #### Minor Fixes and Improvements + - The effect handler for `:dispatch-n` will now ignore `nils`. [See checkin](https://github.com/Day8/re-frame/commit/6efdae438f393f8121a2d6dfbf76db00e6dafbf5) - [#340](https://github.com/Day8/re-frame/pull/340) - - [#341](https://github.com/Day8/re-frame/pull/341) Fix `re-frame.std-interceptors/on-changes` to work even if effect handler does not set `:db`. + - [#341](https://github.com/Day8/re-frame/pull/341) Fix `re-frame.core/on-changes` to work even if event handler does not set `:db`. ## 0.9.4 (2017.06.01) diff --git a/docs/API.md b/docs/API.md index d3475d9..02f84c5 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,12 +1,14 @@ ## The re-frame API Orientation: - 1. The API is provided by the [re-frame.core](/src/re_frame/core.cljc) namespace - 2. The API is quite small - you'll use less than 10 API functions when writing an app. + 1. The API is provided by [re-frame.core](/src/re_frame/core.cljc) which means: + - you should probably browse this namespace sometime + - to use re-frame, you'll have to `require` it + 2. The API is small. Writing an app, you'll use less than 10 API functions. Maybe just 5. 3. There's no auto-generated docs [because of this problem](/src/re_frame/core.cljc#L23-L36) - 4. But below are helpful links to the doc strings of often-used API functions + 4. But below are links to the doc strings of often-used API functions. -## Links To API docs +## Doc Strings For API Functions The core API consists of: - [dispatch](/src/re_frame/router.cljc#L229-L239), [dispatch-sync](/src/re_frame/router.cljc#L247-L259). See also [this FAQ](/docs/FAQs/When-Does-Dispatch-Happen.md) @@ -15,8 +17,8 @@ The core API consists of: - [subscribe](/src/re_frame/subs.cljc#L67-L83) Occasionally, you'll need to use: - - [reg-fx]() XXX - - [reg-cofx]() XXX and [inject-cofx](/src/re_frame/cofx.cljc#L22-L73) + - [reg-fx](/src/re_frame/fx.cljc#L17-L39) + - [reg-cofx](/src/re_frame/cofx.cljc#L14-L21) and [inject-cofx](/src/re_frame/cofx.cljc#L22-L73) And, finally, there are builtin Interceptors which are useful: - [path](/src/re_frame/std_interceptors.cljc#L149-L173) @@ -25,11 +27,11 @@ And, finally, there are builtin Interceptors which are useful: - [and browse the others](/src/re_frame/std_interceptors.cljc) -### Built-in Effect Handlers +## Built-in Effect Handlers -The following built-in effects are effectively part of the API: +The following built-in effects are part of the API: -#### :dispatch-later +### :dispatch-later `dispatch` one or more events after given delays. Expects a collection of maps with two keys: `:ms` and `:dispatch` @@ -51,7 +53,7 @@ usage: {:dispatch [:event-id "param"] } ``` -#### :dispatch-n +### :dispatch-n `dispatch` more than one event. Expects a collection events. @@ -60,7 +62,7 @@ usage: {:dispatch-n (list [:do :all] [:three :of] [:these])} ``` -#### :deregister-event-handler +### :deregister-event-handler removes a previously registered event handler. Expects either a single id ( typically a keyword), or a seq of ids. @@ -74,7 +76,7 @@ or: {:deregister-event-handler [:one-id :another-id]} ``` -#### :db +### :db reset! app-db with a new value. Expects a map. @@ -83,6 +85,7 @@ usage: {:db {:key1 value1 :key2 value2}} ``` +*** Previous: [First Code Walk-Through](CodeWalkthrough.md)       Up: [Index](README.md)       diff --git a/src/re_frame/cofx.cljc b/src/re_frame/cofx.cljc index 7f9a0cf..2869436 100644 --- a/src/re_frame/cofx.cljc +++ b/src/re_frame/cofx.cljc @@ -12,7 +12,13 @@ (assert (re-frame.registrar/kinds kind)) (defn reg-cofx - "" + "Register the given coeffect `handler` for the given coeffect `id`. + + `id` is keyword, often namespaced. + `handler` is a function which takes either one or two values, the first of which is + always `context` and which returns an updated `context`. + + Please see the docs for `inject-cofx` for example use." [id handler] (register-handler kind id handler)) diff --git a/src/re_frame/core.cljc b/src/re_frame/core.cljc index bc557ab..9ec57e7 100644 --- a/src/re_frame/core.cljc +++ b/src/re_frame/core.cljc @@ -57,7 +57,7 @@ ;; -- effects ----------------------------------------------------------------- -(def reg-fx fx/register) +(def reg-fx fx/reg-fx) (def clear-fx (partial registrar/clear-handlers fx/kind)) ;; think unreg-fx ;; -- coeffects --------------------------------------------------------------- diff --git a/src/re_frame/fx.cljc b/src/re_frame/fx.cljc index eb3b56c..ea11354 100644 --- a/src/re_frame/fx.cljc +++ b/src/re_frame/fx.cljc @@ -13,22 +13,51 @@ (def kind :fx) (assert (re-frame.registrar/kinds kind)) -(def register (partial register-handler kind)) + +(defn reg-fx + "Register the given effect `handler` for the given effect `id`. + + `id` is keyword, often namespaced. + `handler` is a side-effecting function which takes a single value and returns nothing. + + Example Use + ----------- + + First registration ... associating `:effect2` with a handler. + + (reg-fx + :effect2 + (fn [value] + ... do something side-effect-y)) + + Then, later if an event handler were to return this effects map: + + {:effect1 42 + :effect2 [1 2]} + + Then the `handler` `fn` we registered previously, using reg-fx, will be + called with a `value` argument of `[1 2]`." + [id handler] + (register-handler kind id handler)) ;; -- Interceptor ------------------------------------------------------------- (def do-fx - "An interceptor whose `:after` executes the instructions in `:effects`. + "An interceptor whose `:after` actions the contents of `:effects`. As a result, + this interceptor is Domino 3. + + This interceptor is silently added (by reg-event-db etc) to the front of + interceptor chains for all events. For each key in `:effects` (a map), it calls the registered `effects handler` - (see `reg-fx` for registration of effects handlers). + (see `reg-fx` for registration of effect handlers). So, if `:effects` was: {:dispatch [:hello 42] :db {...} :undo \"set flag\"} - it will call the registered effects handlers for each of the map's keys: + it will call the registered effect handlers for each of the map's keys: `:dispatch`, `:undo` and `:db`. When calling each handler, provides the map value for that key - so in the example above the effect handler for :dispatch will be given one arg `[:hello 42]`.