docs(state): selection

BioPhoton · BioPhoton · commit 7d474c579ac6 · 2022-03-23T21:57:54.000+01:00
diff --git a/libs/state/selections/README.md b/libs/state/selections/README.md
@@ -6,15 +6,23 @@
 
 ## Slogan
 
-`@rx-angular/state/selections` TBD
+`@rx-angular/state/selections` provides performant and boiler plate free helpers for to craft custom selections with just a few lines of code.
 
 ## Key features
 
-- ✅ 
+- ✅ reduces repetitative code to a minimum
+- ✅ most common problems solved with a 1 liner
+- ✅ distinct values
+- ✅ lazy initialization (avoids `?` in the template)
+- ✅ shared computation
+- ✅ strongly types
+- ✅ fully tested
+
+
 
 ## Demos:
 
-- ⚡ GitHub
+- ⚡ GitHub Todo
 
 ## Install
 
@@ -27,4 +35,3 @@ yarn add @rx-angular/state
 ## Documentation
 
 - [Selections](https://github.com/rx-angular/rx-angular/tree/main/libs/state/selections/docs/Readme.md)
-
diff --git a/libs/state/selections/docs/Readme.md b/libs/state/selections/docs/Readme.md
@@ -59,10 +59,16 @@ As this process contains a lot of gotchas and possible pitfalls in terms of memo
 - Shares computed result with multiple subscriber
 - Select distinct sub-sets
 - Select from static values
-- Fully Tested
-- Fully Typed
+- Fully tested
+- Strongly typed
 
-## Selection owner - Template vs Class
+# Concepts
+
+## Selection composition - lazy vs eager
+
+## Selection composition - functional vs reactive
+
+## Selection setup - Template vs Class
 
 As Observables are cold their resulting stream will only get activated by a subscription.
 This leads to a situations called: "the late subscriber problem" or "the early subscriber problem". (LINK)
@@ -74,8 +80,69 @@ In most cases it's best to go with solving problems on the early subscriber side
 
 ![Selections (4)](https://user-images.githubusercontent.com/10064416/152422883-0b5f6006-7929-4520-b0b2-79eb61e4eb08.png)
 
+# Usage
+
+## select
+
+`select` is the stand-alone version of the `RxState#select` top level method. It helps to create default selection's from a changing state source.
+
+```typescritp
+// emissions: 
+// 0.        - no emission ever happened
+// 1. {a: 1} - incomplete state leads to `?` pollution in the template
+// 2. {a: 1, b: 'a'} - render relevant emission
+// 2. {a: 1, b: 'a'} - same instance emisssion 
+// 3. {a: 1, b: 'a', c: true} - render irrelevant change
+// 4. {a: 1, b: 'b', c: true} - render relevant emission
+const model$: Observable<Partial<{a: number, b: string, c: boolean}>>;
+``` 
+**Problem**
+```html
+<!-- 
+
+Computes 2 times & Renders 0. ❌; 1. ❌; 2. ✅; 3. ❌; .4 ✅
+-->
+<div *rxLet="model$; let vm">
+    B: {{vm?.b}}
+</div>
+B: {{(model$ | push)?.b}}
+```
+
+### single property short hand
+```typescritp
+const vm$ = model$.pipe(select('b'));
+``` 
+```html
+<!-- 
+Computes 1 time & Renders 2. ✅; .4 ✅
+-->
+<div *rxLet="model$; let vm">
+    B: {{vm.b}}
+</div>
+B: {{(model$ | push).b}}
+```
+
+### single operators
+```typescritp
+const vm$: Observable<> = model$.pipe(select(map(({b}) => b === 'a')));
+``` 
+```html
+<!-- 
+Computes 1 time & Renders 2. ✅; .4 ✅
+-->
+<div *rxLet="model$; let vm">
+    B: {{vm.b}}
+</div>
+B: {{(model$ | push).b}}
+```
+
+## selectSlice
+
+## smosh
+  
+## distinctUntilSomeChanges
 
-## Advanced derivation architecture
+# Advanced derivation architecture
 
 **The problem**
 
diff --git a/libs/state/selections/src/lib/smosh.ts b/libs/state/selections/src/lib/smosh.ts
@@ -46,12 +46,15 @@ const resolvedPromise$ = from(resolvedPromise);
  * @param obj - An object of key & Observable values pairs
  * @param durationSelector - An Observable determining the duration for the internal coalescing method
  */
-export function smosh<T extends ObservableMap | (Partial<T> & NotEmpty<T>), U extends Record<string, any>>(
+export function smosh<
+  T extends ObservableMap | (Partial<T> & NotEmpty<T>),
+  U extends Record<string, any>
+>(
   obj: Partial<T>,
   spreads: Observable<U>[] = [],
-  options?: {durationSelector: Observable<any>}
-): Observable<{ [K in keyof T]: ExtractObservableValue<T[K]>} & U> {
-  let {durationSelector} = options || {};
+  options?: { durationSelector: Observable<any> }
+): Observable<{ [K in keyof T]: ExtractObservableValue<T[K]> } & U> {
+  let { durationSelector } = options || {};
   durationSelector = durationSelector || resolvedPromise$;
   const keys = Object.keys(obj) as (keyof T)[];
   const observables = keys.map((key) =>
@@ -73,25 +76,32 @@ export function smosh<T extends ObservableMap | (Partial<T> & NotEmpty<T>), U ex
       }
       return obj;
     })
-  )
-  spreads = spreads.map(o => o.pipe(
-    // we avoid using the nullish operator later ;)
-    filter((v) => v !== undefined),
-    // state "changes" differ from each other, this operator ensures distinct values
-    distinctUntilChanged()
+  );
+  spreads = spreads.map((o) =>
+    o.pipe(
+      // we avoid using the nullish operator later ;)
+      filter((v) => v !== undefined),
+      // state "changes" differ from each other, this operator ensures distinct values
+      distinctUntilChanged()
     )
   );
 
-  return merge(...spreads, obj$).pipe(scan((acc, slice) => {
-    const ks = Object.keys(slice) as (keyof T)[];
-    for (let i = 0; i < ks.length; i++) {
-      acc[ks[i] as any] = slice[ks[i]];
-    }
-    return acc as any;
-  }, {})).pipe(
-    // As combineLatest will emit multiple times for a change in multiple properties we coalesce those emissions together
-    coalesceWith(durationSelector),
-    // by using shareReplay we share the last composition work done to create the accumulated object
-    shareReplay(1)
-  );
+  return combineLatest([...spreads, obj$])
+    .pipe(
+      scan((acc, slices) => {
+        const ks = slices.flatMap((slice) => Object.keys(slice)) as (keyof T)[];
+        slices.forEach((slice) => {
+          for (let i = 0; i < ks.length; i++) {
+            acc[ks[i] as any] = slice[ks[i]];
+          }
+        });
+        return acc as any;
+      }, {})
+    )
+    .pipe(
+      // As combineLatest will emit multiple times for a change in multiple properties we coalesce those emissions together
+      coalesceWith(durationSelector),
+      // by using shareReplay we share the last composition work done to create the accumulated object
+      shareReplay(1)
+    );
 }
