Add OGM documentation

README.md

@@ -79,14 +79,17 @@ CDN: <https://unpkg.com/mobx-utils/mobx-utils.umd.js>
 -   [deepObserve](#deepobserve)
     -   [Parameters](#parameters-17)
     -   [Examples](#examples-16)
+-   [ObservableGroupMap](#observablegroupmap)
+    -   [Examples](#examples-17)
+-   [ObservableMap](#observablemap)
 -   [computedFn](#computedfn)
     -   [Parameters](#parameters-18)
-    -   [Examples](#examples-17)
+    -   [Examples](#examples-18)
 -   [DeepMapEntry](#deepmapentry)
 -   [DeepMap](#deepmap)
 -   [actionAsync](#actionasync)
     -   [Parameters](#parameters-19)
-    -   [Examples](#examples-18)
+    -   [Examples](#examples-19)
 
 ## fromPromise
 
@@ -739,6 +742,33 @@ const disposer = deepObserve(target, (change, path) => {
 })
 ```
 
+## ObservableGroupMap
+
+Reactively sorts a base observable array into multiple observable arrays based on the value of a
+`groupBy: (item: T) => G` function.
+
+This observes the individual computed groupBy values and only updates the source and dest arrays
+when there is an actual change, so this is far more efficient than, for example
+`base.filter(i => groupBy(i) === 'we')`.
+
+No guarantees are made about the order of items in the grouped arrays.
+
+### Examples
+
+```javascript
+const slices = observable([
+    { day: "mo", hours: 12 },
+    { day: "tu", hours: 2 },
+])
+const slicesByDay = new ObservableGroupMap(slices, (slice) => slice.day)
+autorun(() => console.log(
+    slicesByDay.get("mo")?.length ?? 0,
+    slicesByDay.get("we"))) // outputs 1, undefined
+slices[0].day = "we" // outputs 0, [{ day: "we", hours: 12 }]
+```
+
+## ObservableMap
+
 ## computedFn
 
 computedFn takes a function with an arbitrarily amount of arguments,

src/ObservableGroupMap.ts

@@ -14,6 +14,27 @@ interface GrouperItemInfo {
     grouperArrIndex: number
 }
 
+/**
+ * Reactively sorts a base observable array into multiple observable arrays based on the value of a
+ * `groupBy: (item: T) => G` function.
+ *
+ * This observes the individual computed groupBy values and only updates the source and dest arrays
+ * when there is an actual change, so this is far more efficient than, for example
+ * `base.filter(i => groupBy(i) === 'we')`.
+ *
+ * No guarantees are made about the order of items in the grouped arrays.
+ *
+ * @example
+ * const slices = observable([
+ *     { day: "mo", hours: 12 },
+ *     { day: "tu", hours: 2 },
+ * ])
+ * const slicesByDay = new ObservableGroupMap(slices, (slice) => slice.day)
+ * autorun(() => console.log(
+ *     slicesByDay.get("mo")?.length ?? 0,
+ *     slicesByDay.get("we"))) // outputs 1, undefined
+ * slices[0].day = "we" // outputs 0, [{ day: "we", hours: 12 }]
+ */
 export class ObservableGroupMap<G, T> extends ObservableMap<G, IObservableArray<T>> {
     private readonly keyToName: (group: G) => string