comments

src/index.js

@@ -33,32 +33,50 @@ export const deepMap = _.curry((fn, obj, _map = map, is = isTraversable) =>
 // non-deterministic input iterators over discrete state changes
 // aka groupoid category
 // See: https://en.m.wikipedia.org/wiki/Automata_theory#Connection_to_category_theory
+// Use it as:
+//   groupoid(reducer1, reducer2, ...reducerN)(field, ...)
+// Each reducer will receive:
+//   - The result of the previous reducer
+//   - The current value
+//   - The key where the current value is located
+//   - The key names of the parents of the current key
 export const groupoid = (...funs) => function G (
-    field,
-    acc = [],
-    breadth,
-    orientation = 1,
-    path = []
+    field, // input n-dimensional field
+    acc = [], // accumulator
+    breadth, // falsy by default
+    orientation = 1, // > 0 by default
+    path = [] // only used for recursion purposes
 ) {
+    // return the current accumulator if the field is not iterable
     if (!field || typeof field !== 'object') return acc
     let accepted = acc
     let state = acc
     let keys = Object.keys(field)
-    if (orientation < 0) keys = keys.reverse()
-    let key = keys.shift()
     let fN = 0
     let nextBreadth = []
+
+    if (orientation < 0) keys = keys.reverse()
+    let key = keys.shift()
+
+    // unless the user stops us (or we don't have more keys)
     while (state !== false) {
         accepted = state
         let f = funs[fN]
+        // if we have no more functins to look at,
+        // get the next key and reset the function
+        // counter. Lets us avoid having two whiles.
         if (!f) {
             key = keys.shift()
             fN = 0
             f = funs[fN]
         }
         if (!key) break
         let val = field[key]
+        // result of reducer f[fN]
         let result = f(state, val, key, path)
+        // Either we accumulate iterables to go deeper
+        // after all the current level (breadth),
+        // or we go recursive right now.
         if (breadth && val && typeof val === 'object') {
             nextBreadth.push({ val, key })
         } else {