From 91923bfd49e0ab26bc9aaac46e61d4a18882a501 Mon Sep 17 00:00:00 2001
From: Yanick Champoux <yanick@babyl.dyndns.org>
Date: Sun, 2 Feb 2020 23:45:16 -0500
Subject: [PATCH] add documentation

---
 docs/_sidebar.md |  1 +
 docs/concepts.md | 30 ++++++++++++++++++++++++++++++
 docs/updux.md    | 25 +++++++++++++++++++++++++
 3 files changed, 56 insertions(+)
 create mode 100644 docs/concepts.md

diff --git a/docs/_sidebar.md b/docs/_sidebar.md
index 67ee16e..dfdd5c5 100644
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@@ -1,5 +1,6 @@
 <!-- docs/_sidebar.md -->
 
 * [Home](/)
+* [Concepts](concepts.md)
 * API Reference
     * [Updux](updux.md)
diff --git a/docs/concepts.md b/docs/concepts.md
new file mode 100644
index 0000000..65cbbc6
--- /dev/null
+++ b/docs/concepts.md
@@ -0,0 +1,30 @@
+ # Updux concepts
+
+## effects
+
+Updux effects are a superset of redux middleware. I kept that format, and the
+use of `next` mostly because I wanted to give myself a way to alter 
+actions before they hit the reducer, something that `redux-saga` and 
+`rematch` don't allow.
+
+An effect has the signature
+
+```js
+const effect = ({ getState, dispatch, getRootState, selectors}) 
+                => next => action => { ... }
+```
+
+The first argument is like the usual redux middlewareApi, except
+for the availability of selectors and of the root updux's state. 
+
+Also, the function `dispatch` is augmented to be able to be called 
+with the allowed actions as props. For example, assuming that the action
+`complete_todo` has been declared somewhere, then it's possible to do:
+
+```js
+updux.addEffect( 'todo_bankrupcy',
+    ({ getState, dispatch }) => next => action => {
+        getState.forEach( todo => dispatch.complete_todo( todo.id ) );
+    }
+)
+```
diff --git a/docs/updux.md b/docs/updux.md
index d95ba2c..debb225 100644
--- a/docs/updux.md
+++ b/docs/updux.md
@@ -36,6 +36,23 @@ const { actions } = updux({
 
 actions.foo({ x: 1, y: 2 }); // => { type: foo, payload: { x:1, y:2  } }
 actions.bar(1,2);            // => { type: bar, payload: { x:1, y:2  } }
+
+
+#### selectors
+
+Dictionary of selectors for the current updux. The updux also
+inherit its dubduxes' selectors. 
+
+The selectors are available via the class' getter and, for 
+middlewares, the middlewareApi.
+
+```js
+const todoUpdux = new Updux({
+    selectors: {
+        done: state => state.filter( ({done}) => done ),
+        byId: state => targetId => state.find( ({id}) => id === targetId ),
+    }
+}
 ```
 
 #### mutations
@@ -332,3 +349,11 @@ baz();         // => { type: 'baz', payload: undefined }
 
 ```
 
+### selectors
+
+Returns a dictionary of the 
+updux's selectors. Subduxes' selectors 
+are included as well (with the mapping to the sub-state already 
+taken care of you).
+
+