From cc69152427f52526127f6131e20c00b6a0601962 Mon Sep 17 00:00:00 2001
From: Adrian Leonhard <adrianleonhard@gmail.com>
Date: Fri, 10 Apr 2020 15:05:48 +0200
Subject: [PATCH] Add OGM documentation

---
 README.md                 | 34 ++++++++++++++++++++++++++++++++--
 src/ObservableGroupMap.ts | 21 +++++++++++++++++++++
 2 files changed, 53 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 4dca54c..d943002 100644
--- a/README.md
+++ b/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,
diff --git a/src/ObservableGroupMap.ts b/src/ObservableGroupMap.ts
index 93ba2e5..8161b6b 100644
--- a/src/ObservableGroupMap.ts
+++ b/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